tokenslim-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nuoyazhizhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# tokenslim-sdk
+
+[![npm version](https://img.shields.io/npm/v/tokenslim-sdk.svg)](https://www.npmjs.com/package/tokenslim-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Node.js / TypeScript SDK for [TokenSlim](https://github.com/nuoyazhizhou/tokenslim) — a high-performance Rust compression engine for LLM inputs.
+
+Save **50%–95% tokens** on VCS logs, build output, runtime traces, and structured text before sending them to an LLM.
+
+## Install
+
+```bash
+npm install tokenslim-sdk
+# or
+pnpm add tokenslim-sdk
+# or
+yarn add tokenslim-sdk
+```
+
+Requires Node.js **>= 18**.
+
+You also need the TokenSlim server running. Two easy options:
+
+```bash
+# Option A — install the Rust CLI globally
+cargo install tokenslim
+tokenslim serve --port 10086
+
+# Option B — Docker
+docker run -d -p 10086:10086 ghcr.io/nuoyazhizhou/tokenslim:latest
+```
+
+## Quickstart (10 lines)
+
+```ts
+import { TokenSlimClient } from 'tokenslim-sdk';
+
+const client = new TokenSlimClient();              // default http://127.0.0.1:10086
+if (await client.isHealthy()) {
+    const r = await client.compress(longBuildLog, { preset: 'ai' });
+    console.log(`${r.original_tokens} → ${r.compressed_tokens} tokens (saved ${(100 - r.ratio * 100).toFixed(1)}%)`);
+    // Later, re-hydrate:
+    const original = await client.decompress(r.compressed, r.dictionary ?? {});
+}
+```
+
+That's it. No configuration files, no plugin selection — TokenSlim auto-detects the input type and routes to the right plugin (git log, pytest, gradle, JSON, …).
+
+## API Reference
+
+### `new TokenSlimClient(opts?)`
+
+| Option | Default | Description |
+|---|---|---|
+| `host` | `127.0.0.1` | TokenSlim server hostname |
+| `port` | `10086` | TokenSlim server port |
+| `timeoutMs` | `30000` | Per-request timeout |
+| `headers` | `{}` | Extra HTTP headers (auth, etc.) |
+
+### `client.isHealthy(): Promise<boolean>`
+
+Pings `GET /health`. Returns `true` only when the server reports `status: UP`.
+
+### `client.compress(text, opts?): Promise<CompressResponse>`
+
+Compresses a string. `opts` is optional:
+
+```ts
+{
+    preset?: 'ai' | 'balanced' | 'lossless' | string;   // default 'balanced'
+    plugin_hint?: string;                                // e.g. 'vcs_git_plugin'
+}
+```
+
+Returns:
+
+```ts
+{
+    compressed: string;             // compressed output with $P/$T token placeholders
+    original_tokens: number;        // input token count
+    compressed_tokens: number;      // output token count
+    ratio: number;                  // compressed_tokens / original_tokens (0.05 = 95% saving)
+    plugin_used: string;            // 'vcs_git_plugin', 'pytest_plugin', ...
+    dictionary?: Record<string, string>;  // token → original
+}
+```
+
+### `client.decompress(compressed, dictionary): Promise<string>`
+
+Re-hydrates a compressed string back to its original text. Requires the dictionary returned by `compress()`.
+
+### `client.describe(): Promise<{ version, plugin_count, families }>`
+
+Returns server metadata.
+
+### `TokenSlimError`
+
+Thrown on network or non-2xx responses. Has `.statusCode` and `.cause` fields.
+
+```ts
+import { TokenSlimClient, TokenSlimError } from 'tokenslim-sdk';
+
+try {
+    await client.compress(text);
+} catch (e) {
+    if (e instanceof TokenSlimError && e.statusCode === 503) {
+        console.error('TokenSlim server overloaded');
+    }
+}
+```
+
+## Common Recipes
+
+### Wrap a long `git log` for an LLM agent
+
+```ts
+const r = await client.compress(gitLogOutput, { plugin_hint: 'vcs_git_plugin' });
+return `${r.compressed}\n\n[Dictionary]\n${JSON.stringify(r.dictionary)}`;
+```
+
+### Compress test output and assert savings
+
+```ts
+const r = await client.compress(pytestOutput);
+if (r.ratio > 0.5) {
+    throw new Error(`Compression too lossy: ratio=${r.ratio}`);
+}
+```
+
+### Health-aware retry loop
+
+```ts
+async function compressWithRetry(text: string, maxTries = 3): Promise<CompressResponse> {
+    for (let i = 0; i < maxTries; i++) {
+        if (await client.isHealthy()) return client.compress(text);
+        await new Promise((r) => setTimeout(r, 500 * (i + 1)));
+    }
+    throw new Error('TokenSlim server unavailable');
+}
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/tokenslim-server.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// packages/sdk-nodejs/bin/tokenslim-server.js
+//
+// Node.js wrapper for the standalone `tokenslim-server` Rust binary.
+// Mirrors the resolution logic in bin/tokenslim.js but for the server
+// binary. See that file for the full design notes; this one is the
+// server-only counterpart.
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const BINARY_NAME =
+  process.platform === "win32" ? "tokenslim-server.exe" : "tokenslim-server";
+
+const PLATFORM_PKG = {
+  "linux:x64": "@tokenslim/cli-binary-linux-x64-gnu",
+  "linux:arm64": "@tokenslim/cli-binary-linux-arm64-gnu",
+  "darwin:x64": "@tokenslim/cli-binary-darwin-x64",
+  "darwin:arm64": "@tokenslim/cli-binary-darwin-arm64",
+  "win32:x64": "@tokenslim/cli-binary-windows-x64",
+  "win32:arm64": "@tokenslim/cli-binary-windows-arm64",
+};
+
+function locateBinary() {
+  const key = `${process.platform}:${process.arch}`;
+  const pkgName = PLATFORM_PKG[key];
+
+  if (pkgName) {
+    try {
+      const pkgPath = require.resolve(`${pkgName}/package.json`, {
+        paths: [path.dirname(__filename), path.join(path.dirname(__filename), "..", "..")],
+      });
+      const binDir = path.join(path.dirname(pkgPath), "bin");
+      const candidate = path.join(binDir, BINARY_NAME);
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      // optional dep not installed; fall through.
+    }
+  }
+
+  const cached = path.join(__dirname, "..", "vendor", BINARY_NAME);
+  if (fs.existsSync(cached)) return cached;
+
+  return null;
+}
+
+function main() {
+  const bin = locateBinary();
+  if (!bin) {
+    const key = `${process.platform}:${process.arch}`;
+    process.stderr.write(
+      [
+        `tokenslim-server: native binary not found for ${key}.`,
+        ``,
+        `Fix:`,
+        `  1. npm install tokenslim-sdk    (avoid --ignore-optional)`,
+        `  2. cargo install tokenslim-server --locked`,
+        `  3. Download from https://github.com/nuoyazhizhou/tokenslim/releases`,
+        ``,
+        `Tip: the main \`tokenslim\` binary also has a \`serve\` subcommand`,
+        `if you only need the server side.`,
+        ``,
+      ].join("\n"),
+    );
+    process.exit(127);
+  }
+
+  const args = process.argv.slice(2);
+
+  const child = spawn(bin, args, {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  child.on("error", (err) => {
+    process.stderr.write(`tokenslim-server: failed to exec ${bin}: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on("close", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+main();

package/bin/tokenslim.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// packages/sdk-nodejs/bin/tokenslim.js
+//
+// Node.js wrapper for the `tokenslim` Rust CLI binary.
+//
+// Why a wrapper?  We use npm `optionalDependencies` (per-platform packages
+// like @tokenslim/cli-binary-linux-x64-gnu) so the platform-matching binary
+// is installed into node_modules. This wrapper locates that binary at
+// runtime, ensures it is executable, and re-execs it with the original
+// argv.  The end user just sees a normal CLI: `tokenslim --version`,
+// `tokenslim run -- git status`, etc.
+//
+// Resolution order:
+//   1. The platform-specific @tokenslim/cli-binary-* package (preferred;
+//      ships the binary + 60+ plugin configs).
+//   2. A binary cached by scripts/postinstall.js (GitHub Releases fallback).
+//   3. A system `tokenslim` on PATH (developer escape hatch).
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const BINARY_NAME = process.platform === "win32" ? "tokenslim.exe" : "tokenslim";
+
+// Map Node's (platform, arch) → optionalDependency package name we ship.
+const PLATFORM_PKG = {
+  "linux:x64": "@tokenslim/cli-binary-linux-x64-gnu",
+  "linux:arm64": "@tokenslim/cli-binary-linux-arm64-gnu",
+  "darwin:x64": "@tokenslim/cli-binary-darwin-x64",
+  "darwin:arm64": "@tokenslim/cli-binary-darwin-arm64",
+  "win32:x64": "@tokenslim/cli-binary-windows-x64",
+  "win32:arm64": "@tokenslim/cli-binary-windows-arm64",
+};
+
+/**
+ * Locate the tokenslim binary, trying (1) the platform-specific package,
+ * (2) the postinstall cache, (3) PATH. Returns absolute path or null.
+ */
+function locateBinary() {
+  const key = `${process.platform}:${process.arch}`;
+  const pkgName = PLATFORM_PKG[key];
+
+  // (1) Per-platform optional dep, resolved from this file's location so it
+  // works whether the package is installed globally or locally.
+  if (pkgName) {
+    try {
+      // require.resolve walks node_modules upward; throws if not installed.
+      const pkgPath = require.resolve(`${pkgName}/package.json`, {
+        paths: [path.dirname(__filename), path.join(path.dirname(__filename), "..", "..")],
+      });
+      const binDir = path.join(path.dirname(pkgPath), "bin");
+      const candidate = path.join(binDir, BINARY_NAME);
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      // optional dep not installed (e.g. yarn with --ignore-optional); fall through.
+    }
+  }
+
+  // (2) Cache populated by scripts/postinstall.js (GitHub Releases download).
+  const cached = path.join(__dirname, "..", "vendor", BINARY_NAME);
+  if (fs.existsSync(cached)) return cached;
+
+  // (3) System PATH (developer / test mode).
+  return null;
+}
+
+function main() {
+  const bin = locateBinary();
+  if (!bin) {
+    const key = `${process.platform}:${process.arch}`;
+    const pkg = PLATFORM_PKG[key];
+    process.stderr.write(
+      [
+        `tokenslim: native binary not found for ${key}.`,
+        pkg
+          ? `Tried optional package "${pkg}" and the postinstall cache.`
+          : `No prebuilt package for ${key}.`,
+        ``,
+        `Fix:`,
+        pkg
+          ? `  1. Re-run: npm install tokenslim-sdk    (avoid --ignore-optional)`
+          : `  1. Use a supported platform, OR`,
+        `  2. Install Rust and run: cargo install tokenslim --locked`,
+        `  3. Or download from https://github.com/nuoyazhizhou/tokenslim/releases`,
+        ``,
+      ].join("\n"),
+    );
+    process.exit(127);
+  }
+
+  // Forward argv[2..] (skip `node`, the wrapper path).
+  const args = process.argv.slice(2);
+
+  const child = spawn(bin, args, {
+    stdio: "inherit",
+    // Detach so signals (Ctrl-C) propagate to the child correctly on all
+    // platforms. Without this, the wrapper often swallows SIGINT.
+    windowsHide: true,
+  });
+
+  child.on("error", (err) => {
+    process.stderr.write(`tokenslim: failed to exec ${bin}: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  // Forward exit code. Use `close` rather than `exit` so stdio streams are
+  // fully flushed before we hand control back to the shell.
+  child.on("close", (code, signal) => {
+    if (signal) {
+      // Re-raise the signal so the parent shell sees the right status.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+main();

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * TokenSlim Node.js / TypeScript SDK
+ *
+ * Lightweight REST client for the TokenSlim server.
+ * Default endpoint: http://127.0.0.1:10086
+ *
+ * @see https://github.com/nuoyazhizhou/tokenslim
+ */
+/** Health-check response payload from `GET /health`. */
+export interface HealthResponse {
+    status: 'UP' | 'DOWN';
+    version?: string;
+    plugin_count?: number;
+}
+/** Compression request body for `POST /compress`. */
+export interface CompressRequest {
+    text: string;
+    preset?: 'ai' | 'balanced' | 'lossless' | string;
+    plugin_hint?: string;
+}
+/** Compression result. */
+export interface CompressResponse {
+    compressed: string;
+    original_tokens: number;
+    compressed_tokens: number;
+    ratio: number;
+    plugin_used: string;
+    /** Dictionary mapping token placeholders (e.g. `$P1`) to original strings. */
+    dictionary?: Record<string, string>;
+}
+/** Decompression request body for `POST /decompress`. */
+export interface DecompressRequest {
+    compressed: string;
+    dictionary: Record<string, string>;
+}
+/** Decompression result. */
+export interface DecompressResponse {
+    text: string;
+}
+/** Error thrown when the SDK cannot reach the server or the server returns a non-2xx status. */
+export declare class TokenSlimError extends Error {
+    readonly statusCode?: number;
+    readonly cause?: unknown;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        cause?: unknown;
+    });
+}
+/** SDK client options. */
+export interface TokenSlimClientOptions {
+    host?: string;
+    port?: number;
+    /** Request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Extra HTTP headers (e.g. authorization). */
+    headers?: Record<string, string>;
+}
+/**
+ * TokenSlim REST API client.
+ *
+ * @example
+ * ```ts
+ * import { TokenSlimClient } from 'tokenslim-sdk';
+ *
+ * const client = new TokenSlimClient();
+ * if (await client.isHealthy()) {
+ *     const r = await client.compress('git status output...');
+ *     console.log(`${r.original_tokens} → ${r.compressed_tokens} (${(r.ratio * 100).toFixed(1)}%)`);
+ * }
+ * ```
+ */
+export declare class TokenSlimClient {
+    private readonly host;
+    private readonly port;
+    private readonly timeoutMs;
+    private readonly headers;
+    constructor(opts?: TokenSlimClientOptions);
+    /** Ping the server. Returns true if `GET /health` returns `status: UP`. */
+    isHealthy(): Promise<boolean>;
+    /** Compress a text blob via the server. */
+    compress(text: string, opts?: Partial<CompressRequest>): Promise<CompressResponse>;
+    /** Re-hydrate a compressed string back to the original text using its dictionary. */
+    decompress(compressed: string, dictionary: Record<string, string>): Promise<string>;
+    /** Get plugin registry metadata (count, families, available presets). */
+    describe(): Promise<{
+        version: string;
+        plugin_count: number;
+        families: string[];
+    }>;
+    /** Underlying HTTP helper. */
+    private request;
+}
+export default TokenSlimClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,IAAI,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,gGAAgG;AAChG,qBAAa,cAAe,SAAQ,KAAK;IACrC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMnF;AAED,0BAA0B;AAC1B,MAAM,WAAW,sBAAsB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAErC,IAAI,GAAE,sBAA2B;IAO7C,2EAA2E;IACrE,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IASnC,2CAA2C;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQ5F,qFAAqF;IAC/E,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAMzF,yEAAyE;IACnE,QAAQ,IAAI,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;IAIF,8BAA8B;YAChB,OAAO;CAyDxB;AAED,eAAe,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * TokenSlim Node.js / TypeScript SDK
+ *
+ * Lightweight REST client for the TokenSlim server.
+ * Default endpoint: http://127.0.0.1:10086
+ *
+ * @see https://github.com/nuoyazhizhou/tokenslim
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenSlimClient = exports.TokenSlimError = void 0;
+const http = __importStar(require("http"));
+const url_1 = require("url");
+/** Error thrown when the SDK cannot reach the server or the server returns a non-2xx status. */
+class TokenSlimError extends Error {
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = 'TokenSlimError';
+        this.statusCode = opts.statusCode;
+        this.cause = opts.cause;
+    }
+}
+exports.TokenSlimError = TokenSlimError;
+/**
+ * TokenSlim REST API client.
+ *
+ * @example
+ * ```ts
+ * import { TokenSlimClient } from 'tokenslim-sdk';
+ *
+ * const client = new TokenSlimClient();
+ * if (await client.isHealthy()) {
+ *     const r = await client.compress('git status output...');
+ *     console.log(`${r.original_tokens} → ${r.compressed_tokens} (${(r.ratio * 100).toFixed(1)}%)`);
+ * }
+ * ```
+ */
+class TokenSlimClient {
+    constructor(opts = {}) {
+        this.host = opts.host ?? '127.0.0.1';
+        this.port = opts.port ?? 10086;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+        this.headers = opts.headers ?? {};
+    }
+    /** Ping the server. Returns true if `GET /health` returns `status: UP`. */
+    async isHealthy() {
+        try {
+            const res = await this.request('GET', '/health');
+            return res.status === 'UP';
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Compress a text blob via the server. */
+    async compress(text, opts = {}) {
+        if (typeof text !== 'string') {
+            throw new TokenSlimError('compress() expects a string input');
+        }
+        const body = { text, ...opts };
+        return this.request('POST', '/compress', body);
+    }
+    /** Re-hydrate a compressed string back to the original text using its dictionary. */
+    async decompress(compressed, dictionary) {
+        const body = { compressed, dictionary };
+        const res = await this.request('POST', '/decompress', body);
+        return res.text;
+    }
+    /** Get plugin registry metadata (count, families, available presets). */
+    async describe() {
+        return this.request('GET', '/describe');
+    }
+    /** Underlying HTTP helper. */
+    async request(method, path, body) {
+        const payload = body !== undefined ? JSON.stringify(body) : undefined;
+        const url = new url_1.URL(`http://${this.host}:${this.port}${path}`);
+        const headers = {
+            Accept: 'application/json',
+            ...this.headers,
+        };
+        if (payload) {
+            headers['Content-Type'] = 'application/json';
+            headers['Content-Length'] = Buffer.byteLength(payload).toString();
+        }
+        return new Promise((resolve, reject) => {
+            const req = http.request({
+                hostname: url.hostname,
+                port: url.port,
+                path: url.pathname,
+                method,
+                headers,
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    const raw = Buffer.concat(chunks).toString('utf8');
+                    const status = res.statusCode ?? 0;
+                    if (status < 200 || status >= 300) {
+                        reject(new TokenSlimError(`TokenSlim ${method} ${path} failed: HTTP ${status} ${raw.slice(0, 256)}`, { statusCode: status }));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(raw));
+                    }
+                    catch (e) {
+                        reject(new TokenSlimError(`Invalid JSON from ${method} ${path}: ${raw.slice(0, 256)}`, {
+                            cause: e,
+                        }));
+                    }
+                });
+            });
+            req.setTimeout(this.timeoutMs, () => {
+                req.destroy(new TokenSlimError(`Timeout after ${this.timeoutMs}ms calling ${method} ${path}`));
+            });
+            req.on('error', (e) => reject(new TokenSlimError(`Network error: ${e.message}`, { cause: e })));
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+}
+exports.TokenSlimClient = TokenSlimClient;
+exports.default = TokenSlimClient;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "tokenslim-sdk",
+  "version": "0.2.0",
+  "description": "Node.js / TypeScript SDK for TokenSlim — REST client for compressing LLM inputs (also ships the `tokenslim` / `tokenslim-server` binaries for one-stop install).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "tokenslim": "bin/tokenslim.js",
+    "tokenslim-server": "bin/tokenslim-server.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test dist/__tests__/*.test.js"
+  },
+  "keywords": [
+    "tokenslim",
+    "llm",
+    "compression",
+    "tokens",
+    "ai-agents",
+    "log-compression",
+    "cli"
+  ],
+  "author": "nuoyazhizhou",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuoyazhizhou/tokenslim.git",
+    "directory": "packages/sdk-nodejs"
+  },
+  "bugs": {
+    "url": "https://github.com/nuoyazhizhou/tokenslim/issues"
+  },
+  "homepage": "https://github.com/nuoyazhizhou/tokenslim#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "optionalDependencies": {
+    "@tokenslim/cli-binary-linux-x64-gnu": "0.2.0",
+    "@tokenslim/cli-binary-linux-arm64-gnu": "0.2.0",
+    "@tokenslim/cli-binary-darwin-x64": "0.2.0",
+    "@tokenslim/cli-binary-darwin-arm64": "0.2.0",
+    "@tokenslim/cli-binary-windows-x64": "0.2.0",
+    "@tokenslim/cli-binary-windows-arm64": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// packages/sdk-nodejs/scripts/postinstall.js
+//
+// npm `postinstall` hook. Runs after `npm install tokenslim-sdk`.
+//
+// What we do, in order:
+//   1. If the matching @tokenslim/cli-binary-* optional package is already
+//      on disk (npm/yarn/pnpm usually pick the right one automatically),
+//      we just `chmod +x` the binaries and exit. This is the common case.
+//   2. If no optional package is present (e.g. user passed
+//      `--ignore-optional`, or we run on an unsupported platform), we try
+//      to download a matching tarball from the GitHub Release tagged
+//      "v<package-version>". This requires network access.
+//   3. If the download also fails, we log a friendly hint and exit 0.
+//      We intentionally don't fail the install — the SDK JS still works
+//      as a REST client even without the native binary; users who only
+//      need the SDK and have a server elsewhere can ignore the warning.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const https = require("node:https");
+
+const PKG_VERSION = require("../package.json").version;
+const PACKAGE_NAME = "tokenslim-sdk";
+
+// Map (platform, arch) → optional-dependency package name.
+const PLATFORM_PKG = {
+  "linux:x64": "@tokenslim/cli-binary-linux-x64-gnu",
+  "linux:arm64": "@tokenslim/cli-binary-linux-arm64-gnu",
+  "darwin:x64": "@tokenslim/cli-binary-darwin-x64",
+  "darwin:arm64": "@tokenslim/cli-binary-darwin-arm64",
+  "win32:x64": "@tokenslim/cli-binary-windows-x64",
+  "win32:arm64": "@tokenslim/cli-binary-windows-arm64",
+};
+
+function info(msg) {
+  process.stdout.write(`[${PACKAGE_NAME}/postinstall] ${msg}\n`);
+}
+
+function warn(msg) {
+  process.stderr.write(`[${PACKAGE_NAME}/postinstall] WARN: ${msg}\n`);
+}
+
+function vendorDir() {
+  return path.join(__dirname, "..", "vendor");
+}
+
+function chmodX(file) {
+  if (process.platform === "win32") return; // no-op on Windows
+  try {
+    fs.chmodSync(file, 0o755);
+  } catch (e) {
+    warn(`chmod +x failed for ${file}: ${e.message}`);
+  }
+}
+
+function findOptionalBinary() {
+  const key = `${process.platform}:${process.arch}`;
+  const pkgName = PLATFORM_PKG[key];
+  if (!pkgName) return null;
+  try {
+    const pkgJson = require.resolve(`${pkgName}/package.json`, {
+      paths: [
+        path.join(__dirname, "..", "..", ".."),
+        path.join(__dirname, "..", ".."),
+      ],
+    });
+    const binDir = path.join(path.dirname(pkgJson), "bin");
+    if (!fs.existsSync(binDir)) return null;
+    return { pkgName, binDir };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stream a URL to a local file via the built-in `https` module — no
+ * external deps.  Resolves on 2xx, rejects on non-2xx / network error.
+ */
+function downloadToFile(url, dest, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, (res) => {
+      // Handle GitHub Release CDN redirects (302 → S3).
+      if (
+        res.statusCode &&
+        res.statusCode >= 300 &&
+        res.statusCode < 400 &&
+        res.headers.location
+      ) {
+        if (redirectsLeft <= 0) {
+          reject(new Error("too many redirects"));
+          return;
+        }
+        res.resume();
+        downloadToFile(res.headers.location, dest, redirectsLeft - 1)
+          .then(resolve)
+          .catch(reject);
+        return;
+      }
+      if (!res.statusCode || res.statusCode >= 400) {
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        return;
+      }
+      const file = fs.createWriteStream(dest);
+      res.pipe(file);
+      file.on("finish", () => file.close(() => resolve(dest)));
+      file.on("error", reject);
+    });
+    req.on("error", reject);
+    req.setTimeout(60_000, () => req.destroy(new Error("download timeout")));
+  });
+}
+
+async function downloadFromGitHubRelease(binName) {
+  const tag = `v${PKG_VERSION}`;
+  const archive = `${binName}.tar.gz`;
+  const url = `https://github.com/nuoyazhizhou/tokenslim/releases/download/${tag}/${archive}`;
+  const out = path.join(vendorDir(), binName);
+
+  info(`downloading ${url}`);
+  await downloadToFile(url, out);
+  chmodX(out);
+  info(`saved → ${out}`);
+}
+
+function alreadyCached(binName) {
+  const p = path.join(vendorDir(), binName);
+  return fs.existsSync(p);
+}
+
+async function tryGithubReleaseFallback() {
+  const key = `${process.platform}:${process.arch}`;
+  if (!PLATFORM_PKG[key]) return false; // unsupported platform
+
+  const isWin = process.platform === "win32";
+  const tokenslim = isWin ? "tokenslim.exe" : "tokenslim";
+  const server = isWin ? "tokenslim-server.exe" : "tokenslim-server";
+
+  if (alreadyCached(tokenslim) && alreadyCached(server)) return true;
+
+  try {
+    if (!alreadyCached(tokenslim)) {
+      await downloadFromGitHubRelease(tokenslim);
+    }
+    if (!alreadyCached(server)) {
+      await downloadFromGitHubRelease(server);
+    }
+    return true;
+  } catch (e) {
+    warn(`GitHub Release fallback failed: ${e.message}`);
+    warn(
+      `the SDK JS still works as a REST client; the \`tokenslim\` / \`tokenslim-server\` commands will be unavailable.`,
+    );
+    return false;
+  }
+}
+
+async function main() {
+  // (1) The matching optional package brought the binary along.
+  const found = findOptionalBinary();
+  if (found) {
+    info(`platform package found: ${found.pkgName}`);
+    const dir = found.binDir;
+    for (const name of fs.readdirSync(dir)) {
+      const p = path.join(dir, name);
+      const st = fs.statSync(p);
+      if (st.isFile()) chmodX(p);
+    }
+    info(`binaries ready in ${dir}`);
+    return;
+  }
+
+  // (2) GitHub Release fallback. We only attempt this for matching
+  // (platform, arch) so users on unusual platforms (FreeBSD, etc.) just
+  // see a clean warning instead of a download error.
+  info(
+    `no platform-specific package for ${process.platform}/${process.arch}; trying GitHub Release v${PKG_VERSION} ...`,
+  );
+  fs.mkdirSync(vendorDir(), { recursive: true });
+  const ok = await tryGithubReleaseFallback();
+  if (!ok) {
+    warn(
+      `skipping binary install; \`tokenslim\` CLI commands won't be available. SDK HTTP client works normally.`,
+    );
+  }
+}
+
+main().catch((e) => {
+  warn(`unexpected error: ${e && e.stack ? e.stack : e}`);
+  // Never fail npm install on postinstall errors. The user gets the JS
+  // SDK and a clear warning; they can rerun with --foreground-scripts
+  // to see logs and re-attempt.
+  process.exit(0);
+});

package/src/index.ts

@@ -0,0 +1,194 @@
+/**
+ * TokenSlim Node.js / TypeScript SDK
+ *
+ * Lightweight REST client for the TokenSlim server.
+ * Default endpoint: http://127.0.0.1:10086
+ *
+ * @see https://github.com/nuoyazhizhou/tokenslim
+ */
+
+import * as http from 'http';
+import { URL } from 'url';
+
+/** Health-check response payload from `GET /health`. */
+export interface HealthResponse {
+    status: 'UP' | 'DOWN';
+    version?: string;
+    plugin_count?: number;
+}
+
+/** Compression request body for `POST /compress`. */
+export interface CompressRequest {
+    text: string;
+    preset?: 'ai' | 'balanced' | 'lossless' | string;
+    plugin_hint?: string;
+}
+
+/** Compression result. */
+export interface CompressResponse {
+    compressed: string;
+    original_tokens: number;
+    compressed_tokens: number;
+    ratio: number;
+    plugin_used: string;
+    /** Dictionary mapping token placeholders (e.g. `$P1`) to original strings. */
+    dictionary?: Record<string, string>;
+}
+
+/** Decompression request body for `POST /decompress`. */
+export interface DecompressRequest {
+    compressed: string;
+    dictionary: Record<string, string>;
+}
+
+/** Decompression result. */
+export interface DecompressResponse {
+    text: string;
+}
+
+/** Error thrown when the SDK cannot reach the server or the server returns a non-2xx status. */
+export class TokenSlimError extends Error {
+    public readonly statusCode?: number;
+    public readonly cause?: unknown;
+
+    constructor(message: string, opts: { statusCode?: number; cause?: unknown } = {}) {
+        super(message);
+        this.name = 'TokenSlimError';
+        this.statusCode = opts.statusCode;
+        this.cause = opts.cause;
+    }
+}
+
+/** SDK client options. */
+export interface TokenSlimClientOptions {
+    host?: string;
+    port?: number;
+    /** Request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Extra HTTP headers (e.g. authorization). */
+    headers?: Record<string, string>;
+}
+
+/**
+ * TokenSlim REST API client.
+ *
+ * @example
+ * ```ts
+ * import { TokenSlimClient } from 'tokenslim-sdk';
+ *
+ * const client = new TokenSlimClient();
+ * if (await client.isHealthy()) {
+ *     const r = await client.compress('git status output...');
+ *     console.log(`${r.original_tokens} → ${r.compressed_tokens} (${(r.ratio * 100).toFixed(1)}%)`);
+ * }
+ * ```
+ */
+export class TokenSlimClient {
+    private readonly host: string;
+    private readonly port: number;
+    private readonly timeoutMs: number;
+    private readonly headers: Record<string, string>;
+
+    constructor(opts: TokenSlimClientOptions = {}) {
+        this.host = opts.host ?? '127.0.0.1';
+        this.port = opts.port ?? 10086;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.headers = opts.headers ?? {};
+    }
+
+    /** Ping the server. Returns true if `GET /health` returns `status: UP`. */
+    async isHealthy(): Promise<boolean> {
+        try {
+            const res = await this.request<HealthResponse>('GET', '/health');
+            return res.status === 'UP';
+        } catch {
+            return false;
+        }
+    }
+
+    /** Compress a text blob via the server. */
+    async compress(text: string, opts: Partial<CompressRequest> = {}): Promise<CompressResponse> {
+        if (typeof text !== 'string') {
+            throw new TokenSlimError('compress() expects a string input');
+        }
+        const body: CompressRequest = { text, ...opts };
+        return this.request<CompressResponse>('POST', '/compress', body);
+    }
+
+    /** Re-hydrate a compressed string back to the original text using its dictionary. */
+    async decompress(compressed: string, dictionary: Record<string, string>): Promise<string> {
+        const body: DecompressRequest = { compressed, dictionary };
+        const res = await this.request<DecompressResponse>('POST', '/decompress', body);
+        return res.text;
+    }
+
+    /** Get plugin registry metadata (count, families, available presets). */
+    async describe(): Promise<{
+        version: string;
+        plugin_count: number;
+        families: string[];
+    }> {
+        return this.request('GET', '/describe');
+    }
+
+    /** Underlying HTTP helper. */
+    private async request<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T> {
+        const payload = body !== undefined ? JSON.stringify(body) : undefined;
+        const url = new URL(`http://${this.host}:${this.port}${path}`);
+
+        const headers: Record<string, string> = {
+            Accept: 'application/json',
+            ...this.headers,
+        };
+        if (payload) {
+            headers['Content-Type'] = 'application/json';
+            headers['Content-Length'] = Buffer.byteLength(payload).toString();
+        }
+
+        return new Promise<T>((resolve, reject) => {
+            const req = http.request(
+                {
+                    hostname: url.hostname,
+                    port: url.port,
+                    path: url.pathname,
+                    method,
+                    headers,
+                },
+                (res) => {
+                    const chunks: Buffer[] = [];
+                    res.on('data', (c: Buffer) => chunks.push(c));
+                    res.on('end', () => {
+                        const raw = Buffer.concat(chunks).toString('utf8');
+                        const status = res.statusCode ?? 0;
+                        if (status < 200 || status >= 300) {
+                            reject(
+                                new TokenSlimError(
+                                    `TokenSlim ${method} ${path} failed: HTTP ${status} ${raw.slice(0, 256)}`,
+                                    { statusCode: status },
+                                ),
+                            );
+                            return;
+                        }
+                        try {
+                            resolve(JSON.parse(raw) as T);
+                        } catch (e) {
+                            reject(
+                                new TokenSlimError(`Invalid JSON from ${method} ${path}: ${raw.slice(0, 256)}`, {
+                                    cause: e,
+                                }),
+                            );
+                        }
+                    });
+                },
+            );
+            req.setTimeout(this.timeoutMs, () => {
+                req.destroy(new TokenSlimError(`Timeout after ${this.timeoutMs}ms calling ${method} ${path}`));
+            });
+            req.on('error', (e) => reject(new TokenSlimError(`Network error: ${e.message}`, { cause: e })));
+            if (payload) req.write(payload);
+            req.end();
+        });
+    }
+}
+
+export default TokenSlimClient;