@maximem/synap-js-sdk 0.3.0 → 0.4.1

package/src/bridge-manager.js

@@ -1,262 +0,0 @@
-const { spawn, spawnSync } = require('child_process');
-const readline = require('readline');
-const fs = require('fs');
-const {
-  resolveBridgeScriptPath,
-  resolvePythonBin,
-  resolveInstanceId,
-  setupPythonRuntime,
-} = require('./runtime');
-const { createSynapError } = require('./errors');
-
-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,
-          api_key: this.options.apiKey
-            || process.env.SYNAP_API_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(createSynapError(payload.error, payload.error_type));
-      } 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/errors.js

@@ -1,168 +0,0 @@
-'use strict';
-
-class SynapError extends Error {
-  constructor(message, correlationId) {
-    super(message);
-    this.name = 'SynapError';
-    this.correlationId = correlationId || null;
-  }
-}
-
-class SynapTransientError extends SynapError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'SynapTransientError';
-  }
-}
-
-class SynapPermanentError extends SynapError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'SynapPermanentError';
-  }
-}
-
-class NetworkTimeoutError extends SynapTransientError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'NetworkTimeoutError';
-  }
-}
-
-class RateLimitError extends SynapTransientError {
-  constructor(message, retryAfterSeconds, correlationId) {
-    super(message, correlationId);
-    this.name = 'RateLimitError';
-    this.retryAfterSeconds = retryAfterSeconds || null;
-  }
-}
-
-class ServiceUnavailableError extends SynapTransientError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'ServiceUnavailableError';
-  }
-}
-
-class AgentUnavailableError extends SynapTransientError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'AgentUnavailableError';
-  }
-}
-
-class InvalidInputError extends SynapPermanentError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'InvalidInputError';
-  }
-}
-
-class InvalidInstanceIdError extends InvalidInputError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'InvalidInstanceIdError';
-  }
-}
-
-class InvalidConversationIdError extends InvalidInputError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'InvalidConversationIdError';
-  }
-}
-
-class AuthenticationError extends SynapPermanentError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'AuthenticationError';
-  }
-}
-
-class InsufficientCreditsError extends SynapPermanentError {
-  constructor(message, details, correlationId) {
-    super(message, correlationId);
-    this.name = 'InsufficientCreditsError';
-    // Structured details from the server's 402 response body:
-    //   { balance_credits, minimum_required_credits, recovery_url, redeem_url }
-    this.balanceCredits = details && details.balance_credits != null
-      ? Number(details.balance_credits) : null;
-    this.minimumRequiredCredits = details && details.minimum_required_credits != null
-      ? Number(details.minimum_required_credits) : null;
-    this.recoveryUrl = details && details.recovery_url ? details.recovery_url : null;
-    this.redeemUrl = details && details.redeem_url ? details.redeem_url : null;
-  }
-}
-
-class ContextNotFoundError extends SynapPermanentError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'ContextNotFoundError';
-  }
-}
-
-class SessionExpiredError extends SynapPermanentError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'SessionExpiredError';
-  }
-}
-
-class ListeningAlreadyActiveError extends SynapPermanentError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'ListeningAlreadyActiveError';
-  }
-}
-
-class ListeningNotActiveError extends SynapPermanentError {
-  constructor(message, correlationId) {
-    super(message, correlationId);
-    this.name = 'ListeningNotActiveError';
-  }
-}
-
-const ERROR_MAP = {
-  SynapError,
-  SynapTransientError,
-  SynapPermanentError,
-  NetworkTimeoutError,
-  RateLimitError,
-  ServiceUnavailableError,
-  AgentUnavailableError,
-  InvalidInputError,
-  InvalidInstanceIdError,
-  InvalidConversationIdError,
-  AuthenticationError,
-  InsufficientCreditsError,
-  ContextNotFoundError,
-  SessionExpiredError,
-  ListeningAlreadyActiveError,
-  ListeningNotActiveError,
-};
-
-function createSynapError(message, errorType) {
-  const ErrorClass = ERROR_MAP[errorType];
-  if (ErrorClass) return new ErrorClass(message);
-  return new SynapError(message);
-}
-
-module.exports = {
-  SynapError,
-  SynapTransientError,
-  SynapPermanentError,
-  NetworkTimeoutError,
-  RateLimitError,
-  ServiceUnavailableError,
-  AgentUnavailableError,
-  InvalidInputError,
-  InvalidInstanceIdError,
-  InvalidConversationIdError,
-  AuthenticationError,
-  InsufficientCreditsError,
-  ContextNotFoundError,
-  SessionExpiredError,
-  ListeningAlreadyActiveError,
-  ListeningNotActiveError,
-  createSynapError,
-};

package/src/index.js

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

package/src/runtime.js

@@ -1,161 +0,0 @@
-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,
-};