@maximem/synap-js-sdk 0.1.1

package/.env.example

@@ -0,0 +1,47 @@
+# ==============================
+# REQUIRED FOR LIVE SDK CALLS
+# ==============================
+# Synap instance id (from dashboard/login flow)
+SYNAP_INSTANCE_ID=
+
+# One-time bootstrap key/token from dashboard.
+# Required on first initialization for a new instance/cert bootstrap.
+# Usually not required after credentials are already stored at ~/.synap/instances/<instance_id>.
+SYNAP_BOOTSTRAP_TOKEN=
+# Alias accepted by JS bridge (same value as SYNAP_BOOTSTRAP_TOKEN)
+SYNAP_BOOTSTRAP_KEY=
+
+# Synap HTTP endpoint
+SYNAP_BASE_URL=http://<synap-api-host>:8000
+
+# Synap gRPC endpoint
+SYNAP_GRPC_HOST=<synap-grpc-host>
+SYNAP_GRPC_PORT=50051
+SYNAP_GRPC_TLS=false
+
+# ==============================
+# OPTIONAL
+# ==============================
+# Managed runtime home used by `synap-js-sdk setup`
+SYNAP_JS_SDK_HOME=/Users/anish/.synap-js-sdk
+
+# Optional: override Python binary used by bridge/runtime
+SYNAP_PYTHON_BIN=python3
+
+# Setup/install mode for the Python SDK from package indexes
+SYNAP_PY_SDK_PACKAGE=maximem-synap
+SYNAP_PY_SDK_VERSION=
+SYNAP_PYTHON_BOOTSTRAP=python3
+
+# ==============================
+# ADVANCED / OPTIONAL
+# ==============================
+# Enable verbose telemetry event tracing in Python SDK
+SYNAP_TELEMETRY_TRACE_EVENTS=
+
+# Optional env-credential mode keys (only if Python SDK credentials_source=\"env\")
+SYNAP_API_KEY=
+SYNAP_REFRESH_TOKEN=
+SYNAP_MTLS_CERT_PATH=
+SYNAP_MTLS_KEY_PATH=
+SYNAP_CLIENT_ID=

package/README.md

@@ -0,0 +1,266 @@
+# @maximem/synap-js-sdk
+
+JavaScript SDK wrapper for the Synap Python SDK.
+
+This package gives Node.js apps a normal SDK interface, while internally running a Python bridge process that executes the real `maximem_synap` SDK.
+
+## Why this wrapper exists
+
+The Synap Python SDK currently has the full feature surface (gRPC anticipation, ingestion lifecycle, context fetch modes, telemetry hooks). This JS SDK keeps your app code in Node while delegating memory operations to Python.
+
+## Architecture
+
+```text
+Your Node app
+  -> @maximem/synap-js-sdk (JS API)
+    -> BridgeManager (JSON-RPC over stdin/stdout)
+      -> synap_bridge.py
+        -> maximem_synap (Python SDK)
+          -> Synap API + gRPC
+```
+
+## Flow and failure map
+
+```text
+[1] App calls createClient()/client.init()
+  ->
+[2] BridgeManager resolves python path + bridge path
+  -> FAIL A: python not found / bridge file missing
+  ->
+[3] Node spawns synap_bridge.py child process
+  -> FAIL B: process spawn/runtime error
+  ->
+[4] Node sends JSON-RPC "init"
+  ->
+[5] Python imports maximem_synap + builds SDK config
+  -> FAIL C: maximem_synap not installed in chosen python/venv
+  ->
+[6] SDK initialize() + optional gRPC listen
+  -> FAIL D: invalid instance/auth OR API/gRPC endpoint unreachable
+  ->
+[7] App calls add/search/get/delete
+  ->
+[8] Node sends JSON-RPC method
+  -> FAIL E: IPC timeout / broken pipe / bridge crash
+  ->
+[9] Python executes SDK operation
+  -> FAIL F: SDK/server error, bad input, ingestion timeout
+  ->
+[10] Python returns JSON result
+  ->
+[11] Node resolves promise and returns to app
+```
+
+## What this means operationally
+
+Because this is a wrapper SDK, your deployment must include both runtimes:
+
+1. Node.js (for your app + wrapper)
+2. Python (for the bridge + Synap Python SDK)
+3. A virtualenv containing `maximem-synap`
+
+This is the main difference versus pure JS SDKs.
+
+## Install
+
+```bash
+npm install @maximem/synap-js-sdk
+```
+
+Then set up the Python runtime used by the wrapper (JS runtime flow):
+
+```bash
+npx synap-js-sdk setup --sdk-version <PY_SDK_VERSION>
+```
+
+If you omit `--sdk-version`, it installs the latest package configured as `maximem-synap`.
+This wrapper installs the Python SDK from package indexes (PyPI by default), not from local source paths.
+
+If you want TypeScript support from the start, run:
+
+```bash
+npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version <PY_SDK_VERSION> && npx synap-js-sdk setup-ts
+```
+
+## Quick start in a Node project
+
+```js
+const { createClient } = require('@maximem/synap-js-sdk');
+
+const synap = createClient({
+  instanceId: process.env.SYNAP_INSTANCE_ID,
+  bootstrapToken: process.env.SYNAP_BOOTSTRAP_TOKEN,
+  baseUrl: process.env.SYNAP_BASE_URL,
+  grpcHost: process.env.SYNAP_GRPC_HOST,
+  grpcPort: Number(process.env.SYNAP_GRPC_PORT || 50051),
+  grpcUseTls: process.env.SYNAP_GRPC_TLS === 'true',
+});
+
+async function run() {
+  await synap.init();
+
+  await synap.addMemory({
+    userId: 'user-123',
+    messages: [
+      { role: 'user', content: 'My name is Alex and I live in Austin.' },
+      { role: 'assistant', content: 'Got it.' },
+    ],
+  });
+
+  const result = await synap.searchMemory({
+    userId: 'user-123',
+    query: 'Where does the user live?',
+    maxResults: 10,
+  });
+
+  console.log(result);
+  await synap.shutdown();
+}
+
+run().catch(console.error);
+```
+
+## API
+
+### `createClient(options)` / `new SynapClient(options)`
+
+Options:
+
+- `instanceId`: explicit Synap instance id. If omitted, the SDK tries `SYNAP_INSTANCE_ID`, then `~/.synap/instances/*/metadata.json`.
+- `bootstrapToken`: one-time bootstrap token/key (env: `SYNAP_BOOTSTRAP_TOKEN` or `SYNAP_BOOTSTRAP_KEY`). Required on first initialization of a new instance.
+- `baseUrl`, `grpcHost`, `grpcPort`, `grpcUseTls`: Synap endpoints.
+- `pythonBin`: explicit Python path for the bridge.
+- `bridgeScriptPath`: override Python bridge script path.
+- `sdkHome`: home for managed runtime (default `~/.synap-js-sdk`).
+- `venvPath`: override managed venv path.
+- `pythonPackage`: pip package name (default `maximem-synap`).
+- `pythonSdkVersion`: pip version pin.
+- `noDeps`: use pip `--no-deps` during auto setup.
+- `noBuildIsolation`: use pip `--no-build-isolation` during auto setup.
+- `upgrade`: use pip `--upgrade` during auto setup.
+- `forceRecreateVenv`: recreate managed venv during auto setup.
+- `autoSetup`: if `true`, runtime setup is attempted automatically when Python is missing.
+
+### Methods
+
+- `init()`
+- `addMemory({ userId, messages })`
+- `searchMemory({ userId, query, maxResults })`
+- `getMemories({ userId })`
+- `deleteMemory({ userId, memoryId })`
+- `shutdown()`
+
+## CLI
+
+```bash
+synap-js-sdk setup [options]
+synap-js-sdk setup-ts [options]
+```
+
+Options:
+
+`setup`:
+- `--python <bin>`: bootstrap Python command (default `python3`)
+- `--sdk-home <path>`: runtime home directory
+- `--venv <path>`: virtualenv path
+- `--package <name>`: Python package name
+- `--sdk-version <ver>`: Python SDK version pin
+- `--no-deps`: install package with no dependency resolution
+- `--no-build-isolation`: disable pip build isolation
+- `--upgrade`: use pip `--upgrade`
+- `--force-recreate-venv`: recreate venv
+
+`setup-ts`:
+- `--project-dir <path>`: target Node project (default: current working directory)
+- `--package-manager <name>`: one of `npm`, `pnpm`, `yarn`, `bun` (auto-detected by lockfile if omitted)
+- `--skip-install`: skip TypeScript dependency install (`typescript`, `@types/node`)
+- `--tsconfig-path <path>`: output path for generated tsconfig (default: `tsconfig.json`)
+- `--wrapper-path <path>`: output path for generated typed wrapper (default: `src/synap.ts`)
+- `--no-wrapper`: do not generate typed wrapper file
+- `--force`: overwrite generated files if they already exist
+
+## TypeScript Extension Flow
+
+Use this when a project already has `@maximem/synap-js-sdk` installed and wants type safety without rewriting runtime JS:
+
+1. Run `npx synap-js-sdk setup-ts`
+2. This installs `typescript` and `@types/node` (unless `--skip-install`)
+3. This generates `tsconfig.json` (if missing)
+4. This generates `src/synap.ts` typed wrapper (unless `--no-wrapper`)
+
+Programmatic alternative:
+
+```js
+const { setupTypeScriptExtension } = require('@maximem/synap-js-sdk');
+
+setupTypeScriptExtension({ projectDir: process.cwd() });
+```
+
+## Environment template
+
+Use the provided template:
+
+```bash
+cp .env.example .env
+```
+
+Template file: `.env.example`
+
+## EC2 + Docker flow (recommended)
+
+Build time should install Node deps and Python runtime once, not on every container start.
+
+```dockerfile
+FROM node:20-bullseye
+
+RUN apt-get update && apt-get install -y python3 python3-venv && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+# Install wrapper python runtime deterministically
+RUN npx synap-js-sdk setup --python python3 --sdk-home /opt/synap-js-sdk --sdk-version <PY_SDK_VERSION>
+
+COPY . .
+
+ENV SYNAP_JS_SDK_HOME=/opt/synap-js-sdk
+ENV SYNAP_BASE_URL=http://<synap-api-host>:8000
+ENV SYNAP_GRPC_HOST=<synap-grpc-host>
+ENV SYNAP_GRPC_PORT=50051
+ENV SYNAP_GRPC_TLS=false
+
+CMD ["node", "server.js"]
+```
+
+Runtime flow in container:
+
+1. Node app starts.
+2. First Synap call starts Python bridge process.
+3. Bridge sends `init` to Python SDK.
+4. API methods run through JSON-RPC.
+5. On shutdown, wrapper sends `shutdown` and stops bridge.
+
+## Versioning and compatibility matrix
+
+Recommended policy:
+
+1. Keep JS and Python SDK on the same semantic version (`x.y.z`).
+2. Publish JS only after Python package `x.y.z` is available.
+3. CI release pipeline should verify `pip install maximem-synap==x.y.z` before npm publish.
+
+Even with same-version policy, keep a compatibility table in docs for rollback safety:
+
+```text
+JS 1.3.x -> Python 1.3.x
+JS 1.2.x -> Python 1.2.x
+```
+
+## Failure modes to expect
+
+- Python not installed or not found
+- Bridge process crash/restart
+- pip install failure due to network/private index
+- auth/instance id missing or expired
+
+Treat this SDK as a managed dual-runtime component in production.

package/bin/synap-js-sdk.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+const { setupPythonRuntime } = require('../src/runtime');
+const { setupTypeScriptExtension } = require('../src/setup-typescript');
+
+function parseArgs(argv) {
+  const args = { _: [] };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (!token.startsWith('--')) {
+      args._.push(token);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[i + 1];
+
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+      continue;
+    }
+
+    args[key] = next;
+    i += 1;
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log(`synap-js-sdk
+
+Usage:
+  synap-js-sdk setup [options]
+  synap-js-sdk setup-ts [options]
+
+setup options:
+  --python <bin>             Python bootstrap binary (default: python3)
+  --sdk-home <path>          SDK home (default: ~/.synap-js-sdk)
+  --venv <path>              Virtualenv path (default: <sdk-home>/.venv)
+  --package <name>           Python package name (default: maximem-synap)
+  --sdk-version <ver>        Python SDK version to install
+  --no-deps                  Install without dependencies
+  --no-build-isolation       Disable pip build isolation
+  --upgrade                  Use pip --upgrade
+  --force-recreate-venv      Recreate virtualenv
+
+setup-ts options:
+  --project-dir <path>       Target Node project directory (default: cwd)
+  --package-manager <name>   npm | pnpm | yarn | bun (auto-detect if omitted)
+  --skip-install             Skip installing typescript and @types/node
+  --tsconfig-path <path>     tsconfig output path (default: tsconfig.json)
+  --wrapper-path <path>      Typed wrapper output path (default: src/synap.ts)
+  --no-wrapper               Do not generate the typed wrapper file
+  --force                    Overwrite generated files when they already exist
+
+global:
+  --help                     Show this help
+`);
+}
+
+async function run() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  if (!command || args.help || command === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === 'setup') {
+    try {
+      const result = await setupPythonRuntime({
+        pythonBootstrap: args.python,
+        sdkHome: args['sdk-home'],
+        venvPath: args.venv,
+        pythonPackage: args.package,
+        pythonSdkVersion: args['sdk-version'],
+        noDeps: !!args['no-deps'],
+        noBuildIsolation: !!args['no-build-isolation'],
+        upgrade: !!args.upgrade,
+        forceRecreateVenv: !!args['force-recreate-venv'],
+      });
+
+      console.log('Synap JS SDK Python runtime setup complete.');
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    } catch (error) {
+      console.error('Setup failed:');
+      console.error(error.message || String(error));
+      process.exit(1);
+    }
+  }
+
+  if (command === 'setup-ts') {
+    try {
+      const result = await setupTypeScriptExtension({
+        projectDir: args['project-dir'],
+        packageManager: args['package-manager'],
+        skipInstall: !!args['skip-install'],
+        tsconfigPath: args['tsconfig-path'],
+        wrapperPath: args['wrapper-path'],
+        noWrapper: !!args['no-wrapper'],
+        force: !!args.force,
+      });
+
+      console.log('Synap JS SDK TypeScript extension setup complete.');
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    } catch (error) {
+      console.error('TypeScript setup failed:');
+      console.error(error.message || String(error));
+      process.exit(1);
+    }
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+run();