@maximem/synap-js-sdk 0.3.0 → 0.4.1

package/MIGRATING.md

@@ -0,0 +1,147 @@
+# Migrating from 0.3.x to 0.4
+
+`@maximem/synap-js-sdk` 0.4 is a **native TypeScript SDK**. It no longer spawns
+a Python subprocess.
+
+## The short version
+
+```bash
+npm install @maximem/synap-js-sdk
+```
+
+Then delete any `npx synap-js-sdk setup` step from your install or CI scripts.
+Most code needs no other change.
+
+## Breaking changes
+
+### There is no setup step
+
+0.3.x had two: `npx synap-js-sdk setup` (built a Python virtualenv) and
+`npx synap-js-sdk setup-ts` (installed `typescript` + `@types/node` and wrote a
+tsconfig). Neither exists in 0.4. Installing the package is the whole
+installation, and types ship inside it.
+
+### Python is no longer required, or used
+
+0.3.x shipped a JSON-RPC bridge: Node spawned a Python interpreter and talked to
+the real SDK over stdin/stdout. That required Python 3.11+ on every host, made
+the package unusable anywhere without a process spawn, and meant every call
+crossed a serialised pipe.
+
+0.4 talks to the API directly.
+
+- **Remove** `npx synap-js-sdk setup` from postinstall and CI.
+- `~/.synap-js-sdk/.venv` is now orphaned. It is safe to delete.
+- These environment variables no longer do anything: `SYNAP_JS_SDK_HOME`,
+  `SYNAP_PYTHON_BIN`, `SYNAP_PYTHON_BOOTSTRAP`, `SYNAP_PY_SDK_PACKAGE`,
+  `SYNAP_PY_SDK_VERSION`.
+- The `synap-js-sdk` command still exists and still exits 0, so an un-updated
+  script will not break your build. It prints a notice and does nothing.
+
+### Node 20 is the minimum
+
+Node 18 is end-of-life, and `globalThis.crypto` is only unflagged from Node 19.
+
+### `listen()` is now opt-in
+
+0.3.x started a gRPC anticipation stream **automatically** during init. Every
+user had one whether they wanted it or not.
+
+In 0.4 you ask for it explicitly. Be aware of what that means for your bill:
+the anticipation stream is what lets the SDK answer some retrievals from a
+locally cached bundle. Without it, those turns become billed cloud fetches. If
+you were relying on that behavior, opt back in.
+
+> The stream needs the optional peers: `npm install @grpc/grpc-js
+> @grpc/proto-loader`. It is Node-only. Edge runtimes and Workers cannot host
+> gRPC at all, so importing the SDK there stays safe and only the stream is
+> unavailable.
+
+### The local cache no longer persists across restarts
+
+The Python SDK cached to SQLite, so a restarted process kept its cache. The JS
+SDK caches in memory.
+
+This is a **billing** change, not only a latency one: a cache miss is a metered
+retrieval. Long-lived servers are largely unaffected. Short-lived processes and
+serverless functions will see more cloud fetches. A pluggable cache backend is
+available if you want to add Redis.
+
+### Deleting by user is gone
+
+```js
+// 0.3.x -- silently did nothing in serverless, and reported success
+await client.deleteMemory({ userId: 'u1' });
+
+// 0.4
+await client.memories.delete(memoryId);
+```
+
+The old form tracked memory ids in a process-local dictionary. In any
+serverless or multi-process deployment that dictionary was empty, so the call
+deleted nothing and returned `{ success: true, deletedCount: 0 }`. It now
+throws instead of quietly lying.
+
+### Timestamps are proper ISO-8601
+
+The bridge stringified datetimes through Python's `str()`, producing
+`2026-08-12 10:00:00+00:00` -- a space instead of the `T`. Native JS emits
+`2026-08-12T10:00:00+00:00`. This is a fix, but it is still a change if you
+were parsing those strings.
+
+### True concurrency
+
+The bridge serialised every call through one pipe. Concurrent calls are now
+genuinely concurrent, which is faster and also means server rate limits the
+pipe used to mask can now be reached. If you fan out hard, cap your own
+concurrency.
+
+## What did NOT change
+
+Your call sites, in almost every case.
+
+```js
+// Unchanged
+const ctx = await client.user.context.fetch({ user_id: 'u1', search_query: ['email'] });
+await client.memories.create({ document: 'text', user_id: 'u1' });
+```
+
+- Both the namespaced (`client.user.context.fetch`) and legacy camelCase
+  (`client.fetchUserContext`) surfaces still work.
+- **They still return different shapes**, exactly as before: namespaced returns
+  raw `snake_case`, camelCase returns normalised `camelCase`. Converging them
+  would break one set of callers, so it is deferred.
+- Both `user_id` and `userId` spellings are still accepted everywhere.
+- `client.init()` still exists as a no-op.
+
+## New in 0.4
+
+- **Runs where Python could not**: Edge, Workers and browsers, for the HTTP
+  paths. Only the gRPC stream is Node-only.
+- **Real types**, generated from the source rather than hand-written.
+- **A typed error taxonomy** mirroring the Python SDK. Every error carries a
+  stable `.code`, which is what you should branch on:
+
+  ```js
+  import { isSynapError } from '@maximem/synap-js-sdk';
+
+  try { await client.memories.create({ document }); }
+  catch (e) {
+    if (isSynapError(e) && e.code === 'insufficient_credits') { /* top up */ }
+  }
+  ```
+
+  Prefer `.code` over `instanceof` at a package boundary: with dual ESM/CJS a
+  consumer can end up holding two copies of a class. (`instanceof` is made to
+  work across copies too, but `.code` is the documented contract.)
+- **Explicit lifecycle.** Call `await client.shutdown()` when you are done. The
+  SDK does not register `process.on('exit')` handlers: they leak a listener per
+  client, never fire in Lambda, and `process` does not exist in Workers.
+
+## Staying on 0.3.x
+
+```bash
+npm install @maximem/synap-js-sdk@legacy
+```
+
+0.3.x remains installable under the `legacy` dist-tag and is not deprecated.

package/README.md

@@ -1,11 +1,10 @@
 # @maximem/synap-js-sdk
 
-Node.js wrapper for the Synap Python SDK.
+Native TypeScript SDK for [Synap](https://synap.maximem.ai) context and memory
+management.
 
-## Prerequisites
-
-- Node.js 18+
-- Python 3.8+
+**No Python required.** 0.4 replaced the Python-subprocess bridge with a native
+client. Upgrading from 0.3.x? See [MIGRATING.md](./MIGRATING.md).
 
 ## Install
 
@@ -13,109 +12,123 @@ Node.js wrapper for the Synap Python SDK.
 npm install @maximem/synap-js-sdk
 ```
 
-## Setup (JS Runtime)
+Requires Node.js 20+. **That is the whole installation.** There is no setup
+command, and TypeScript needs no extra step: types ship in the package.
 
-Install the Python runtime used by the wrapper:
+Verified against TypeScript 5.7 and 7.0 with `moduleResolution` set to `node`,
+`node16`, `nodenext` and `bundler`.
 
-```bash
-npx synap-js-sdk setup --sdk-version 0.2.0
-```
+## Quick start
 
-If you want the latest Python SDK version, omit `--sdk-version` and pass `--upgrade`.
+```ts
+import { SynapClient } from '@maximem/synap-js-sdk';
 
-## Verify Runtime
+const client = new SynapClient({ apiKey: process.env.SYNAP_API_KEY });
 
-macOS/Linux:
-
-```bash
-~/.synap-js-sdk/.venv/bin/python -c "import maximem_synap; print(maximem_synap.__version__)"
-```
+// Store
+await client.memories.create({
+  document: 'The user prefers aisle seats on long-haul flights.',
+  user_id: 'user-123',
+  // Optional. Defaults to 'ai-chat-conversation'. It selects the extraction
+  // path, so setting it wrongly stores less from the same text.
+  document_type: 'ai-chat-conversation',
+});
 
-Windows:
+// Retrieve
+const context = await client.user.context.fetch({
+  user_id: 'user-123',
+  search_query: ['seat preference'],
+});
 
-```powershell
-$env:USERPROFILE\.synap-js-sdk\.venv\Scripts\python.exe -c "import maximem_synap; print(maximem_synap.__version__)"
+await client.shutdown();
 ```
 
-## Required Environment Variable
+## Scopes
 
-- `SYNAP_API_KEY` (from the Synap dashboard — Instances → Generate API Key)
+Scopes are **client > customer > user**. A narrower request also matches
+broader-scope memories.
 
-The SDK uses the default Synap cloud endpoints automatically. `SYNAP_BASE_URL`,
-`SYNAP_GRPC_HOST`, `SYNAP_GRPC_PORT`, and `SYNAP_GRPC_TLS` are only needed for
-advanced overrides such as local development or custom environments.
+```ts
+await client.user.context.fetch({ user_id, customer_id });
+await client.customer.context.fetch({ customer_id });
+await client.client.context.fetch({});
+```
 
-## Quick Start (JavaScript)
+`conversation_id` is **not** a scope tier. It groups turns within a scope, and
+narrows a fetch rather than selecting a different one.
 
-```js
-const { createClient } = require('@maximem/synap-js-sdk');
+## Errors
 
-const synap = createClient({
-  apiKey: process.env.SYNAP_API_KEY,
-});
+Every error carries a stable `.code`. Branch on that rather than on the class,
+because a dual ESM/CJS dependency graph can hand you two copies of the same
+class:
 
-async function run() {
-  await synap.init();
-
-  await synap.addMemory({
-    userId: 'user-123',
-    customerId: 'customer-456',
-    conversationId: 'conv-123',
-    messages: [{ role: 'user', content: 'My name is Alex and I live in Austin.' }],
-  });
-
-  const context = await synap.fetchUserContext({
-    userId: 'user-123',
-    customerId: 'customer-456',
-    conversationId: 'conv-123',
-    searchQuery: ['Where does the user live?'],
-    maxResults: 10,
-  });
-
-  console.log(context.facts);
-
-  const promptContext = await synap.getContextForPrompt({
-    conversationId: 'conv-123',
-    style: 'structured',
-  });
-
-  console.log(promptContext.formattedContext);
-  await synap.shutdown();
-}
+```ts
+import { isSynapError } from '@maximem/synap-js-sdk';
 
-run().catch(console.error);
+try {
+  await client.memories.create({ document, user_id });
+} catch (e) {
+  if (!isSynapError(e)) throw e;
+  switch (e.code) {
+    case 'insufficient_credits': /* top up */ break;
+    case 'rate_limit':           /* e.retryAfterSeconds */ break;
+    case 'authentication':       /* bad key */ break;
+    default: throw e;
+  }
+}
 ```
 
-## TypeScript Extension Setup
+Transient errors are retried automatically. Ingestion is deliberately **not**
+retried when a failure leaves the outcome unknown, because a retry would store
+and bill twice.
 
-Add TypeScript support to an existing JS project:
+## Runtime support
 
-```bash
-npx synap-js-sdk setup-ts
-```
+| Runtime | HTTP context + memories | gRPC anticipation stream |
+|---|---|---|
+| Node.js 20+ | Yes | Yes (opt-in) |
+| Bun | Yes | Unverified |
+| Deno 2 | Yes | Unverified |
+| Vercel Edge | Yes | No |
+| Cloudflare Workers | Yes | No |
+| Browser | Yes (do not ship an API key) | No |
 
-This command can:
-- install `typescript` and `@types/node`
-- generate `tsconfig.json` (if missing)
-- generate `src/synap.ts` typed wrapper (if missing)
+Edge and Workers cannot run gRPC at all: it needs raw TCP and `node:http2`,
+which they do not provide. Bun and Deno have both, so gRPC is plausible on each,
+but **bidirectional streaming has not been tested there**, so those cells stay
+unverified rather than claimed either way.
 
-## Single-Flow Setup (JS + TS)
+Importing the SDK on Edge is safe: gRPC lives behind the
+`@maximem/synap-js-sdk/grpc` subpath and is only ever loaded lazily.
 
-```bash
-npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version 0.2.0 && npx synap-js-sdk setup-ts
-```
+## Configuration
 
-## API Notes
+| Option | Default | Notes |
+|---|---|---|
+| `apiKey` | `SYNAP_API_KEY` | Required. |
+| `clientId` | `SYNAP_CLIENT_ID` | Skips a `whoami` round trip. |
+| `baseUrl` | prod | |
+| `heartbeat` | `false` | Keeps the connection warm. Worth it for a long-lived process, pointless in serverless. |
+| `timeouts` | 5s connect / 30s read | |
+| `retryPolicy` | 3 attempts | |
 
-- `addMemory()` now requires `customerId` to match the Python SDK's explicit ingestion scope.
-- `fetchUserContext()`, `fetchCustomerContext()`, and `fetchClientContext()` expose the structured Python `ContextResponse` surface in JS/TS.
-- `getContextForPrompt()` exposes compacted context plus recent un-compacted messages.
-- `searchMemory()` and `getMemories()` remain convenience helpers built on top of user-scoped context fetches.
-- Temporal fields are exposed in JS/TS as `eventDate`, `validUntil`, `temporalCategory`, `temporalConfidence`, plus top-level `temporalEvents`.
+Environment flags are read at call time, so you can toggle them at runtime:
+`SYNAP_SDK_CACHE_RECALL_BYPASS`, `SYNAP_SDK_CACHE_HONOR_TTL_HINT`,
+`SYNAP_SDK_CACHE_INVALIDATE_ON_WRITE`, `SYNAP_SDK_CACHE_COVERAGE_MIN`,
+`SYNAP_SDK_CACHE_MAX_ENTRY_AGE`.
 
-## CLI Commands
+## Development
 
 ```bash
-synap-js-sdk setup [options]
-synap-js-sdk setup-ts [options]
+npm install
+npm test
+npm run build
+npm run typecheck
+npm run sync-behavior   # after changing synap/sdk/CONTRACT/**
 ```
+
+Retrieval behavior (recall-bypass patterns, BM25 thresholds, the stemmer) is
+**not defined in this package**. It lives in `synap/sdk/CONTRACT/`, shared
+byte-identically with the Python SDK, and both SDKs run the same conformance
+corpus. Never edit the vendored copy in `src/behavior/`.

package/bin/synap-js-sdk.js

@@ -1,124 +1,47 @@
 #!/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;
+/**
+ * Compatibility shim.
+ *
+ * `npx synap-js-sdk setup` used to build a Python virtualenv and install the
+ * Python SDK into it. Since 1.0 the SDK is native TypeScript, so there is
+ * nothing to set up.
+ *
+ * The command is kept, and kept exiting 0, because it appears in published
+ * documentation and in customers' postinstall and CI scripts. Removing the
+ * binary would turn a no-longer-needed step into a hard failure on upgrade.
+ *
+ * ESM, not CommonJS: package.json declares "type": "module", so a `require`
+ * here would throw ERR_REQUIRE_ESM on every invocation.
+ */
+
+const [, , command] = process.argv;
+
+const NOTE = `
+@maximem/synap-js-sdk 1.x is a native TypeScript SDK. It does not use Python,
+so there is no setup step and this command does nothing.
+
+If you are upgrading from 0.3.x:
+  - Remove any "npx synap-js-sdk setup" step from your install or CI scripts.
+  - ~/.synap-js-sdk/.venv is now orphaned and safe to delete.
+  - Node 20 or newer is required.
+  - listen() is now opt-in rather than started automatically.
+
+See MIGRATING.md in the package for the full list.
+`.trim();
+
+switch (command) {
+  case 'setup':
+  case 'setup-ts':
+  case undefined:
+    console.log(NOTE);
+    break;
+  case '--version':
+  case '-v':
+    console.log(process.env['npm_package_version'] ?? '1.x');
+    break;
+  default:
+    console.log(`Unknown command: ${command}\n\n${NOTE}`);
+    // Still exit 0: an unknown subcommand in a legacy script should not break
+    // a customer's build on upgrade.
+    break;
 }
-
-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();

package/dist/anticipation-cache-ARYEEKMU.cjs

@@ -0,0 +1,10 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkRB57I2IQcjs = require('./chunk-RB57I2IQ.cjs');
+require('./chunk-ZKOJDUN4.cjs');
+
+
+
+exports.ANY_SCOPE = _chunkRB57I2IQcjs.ANY_SCOPE; exports.AnticipationCache = _chunkRB57I2IQcjs.AnticipationCache;
+//# sourceMappingURL=anticipation-cache-ARYEEKMU.cjs.map

package/dist/anticipation-cache-ARYEEKMU.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/anish/maximemai/maximem_synap/synap/sdk/js/dist/anticipation-cache-ARYEEKMU.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACF,iHAAC","file":"/Users/anish/maximemai/maximem_synap/synap/sdk/js/dist/anticipation-cache-ARYEEKMU.cjs"}