@agntcy/slim-bindings-node 0.1.4

package/README.md

@@ -0,0 +1,104 @@
+# SLIM Node.js Bindings
+
+Node.js bindings for SLIM using UniFFI.
+Bindings generated with [uniffi-bindgen-node](https://github.com/livekit/uniffi-bindgen-node).
+
+## Installation
+
+For released versions, install from npm (no Rust or build required):
+
+```bash
+npm install @agntcy/slim-bindings-node
+```
+
+This installs the main package and the matching platform-specific native addon for your OS/arch.
+
+To build from source (e.g. for development or unsupported platforms), see [Build from source](#build-from-source) below.
+
+## Prerequisites (build from source)
+
+- Rust toolchain
+- Node.js >= 18
+- [Task](https://taskfile.dev/)
+
+## Usage
+
+### 1. Generate Bindings (build from source)
+
+```bash
+task generate
+```
+
+### 2. Run P2P Examples
+
+```bash
+# Terminal 1: Start the server
+task example:server
+
+# Terminal 2: Start Alice (receiver)
+task example:alice
+
+# Terminal 3: Start Bob (sender) 
+task example:bob
+```
+
+### Available Commands
+
+```bash
+task generate         # Generate bindings
+task clean            # Clean build artifacts
+task example:server   # Run server
+task example:alice    # Run Alice receiver
+task example:bob      # Run Bob sender
+```
+
+## Build Process
+
+The bindings generation includes patching to fix compatibility issues between `uniffi-bindgen-node` (code generator) and `uniffi-bindgen-react-native` (runtime library):
+
+- **Naming fixes**: `FfiConverterBytes` → `FfiConverterArrayBuffer`
+- **Buffer wrapping**: Proper RustBuffer allocation for byte arrays
+- **Pointer conversions**: BigInt → Number for FFI calls
+- **Error handling**: Enhanced error extraction from Rust
+
+## FFI Type Conversions
+
+The generated bindings use `bigint` in TypeScript signatures for u64 types, but the underlying FFI layer returns JavaScript `number` types at runtime. Application code handles conversions at API boundaries:
+
+```typescript
+// connectAsync returns a number at runtime, despite bigint type signature
+const connId = await service.connectAsync(config);
+
+// Convert to BigInt when passing to methods expecting bigint
+await app.subscribeAsync(name, BigInt(connId));
+
+// When using with methods that need number (for direct FFI calls)
+app.setRoute(name, Number(connId));
+```
+
+**Key conversions:**
+- `connectAsync` returns `number` → convert to `BigInt()` for TypeScript bigint parameters
+- When calling FFI methods with u64 params → convert to `Number()` if passing bigint
+
+This explicit conversion at API boundaries ensures type safety and makes FFI requirements visible.
+
+## Build from source
+
+If you need to build from source (development or a platform not yet published):
+
+1. Ensure Rust and Task are installed.
+2. Run `task generate` (builds the Rust lib and generates Node bindings).
+3. Use the bindings from `generated/` or run the examples with `task example:server`, etc.
+
+## Publishing (maintainers)
+
+- **Dry run**: From `data-plane/bindings/node`, run `npm pack` to produce a tarball and inspect contents (main package: no `generated/`; platform packages: `task pack:platform TARGET=<target>` then check `dist/node-<platform>.tgz`).
+- **Version**: Set in package.json; CI derives version from tag `slim-bindings-v*` via `.github/scripts/get-binding-version.sh`.
+- **Secrets**: `NPM_TOKEN` must be set in the repo for `npm publish`.
+
+## Resources
+
+- [uniffi-bindgen-node](https://github.com/livekit/uniffi-bindgen-node)
+- [UniFFI Documentation](https://mozilla.github.io/uniffi-rs/)
+- [ffi-rs](https://www.npmjs.com/package/ffi-rs)
+- [SLIM Core](https://github.com/agntcy/slim)

package/index.d.ts

@@ -0,0 +1,8 @@
+// Copyright AGNTCY Contributors (https://github.com/agntcy)
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Type definitions for @agntcy/slim-bindings-node.
+ * Full types are in types/ (generated from bindings before publish).
+ */
+export * from './types/slim-bindings-node';

package/index.js

@@ -0,0 +1,40 @@
+// Copyright AGNTCY Contributors (https://github.com/agntcy)
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict';
+
+/**
+ * Resolves the platform id for the current Node process.
+ * Must match the optionalDependency package suffixes.
+ */
+function getCurrentPlatformId() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === 'darwin') {
+    return arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  }
+  if (platform === 'linux') {
+    return arch === 'arm64' ? 'linux-arm64-gnu' : 'linux-x64-gnu';
+  }
+  if (platform === 'win32') {
+    return arch === 'arm64' ? 'win32-arm64-msvc' : 'win32-x64-msvc';
+  }
+  throw new Error(`Unsupported platform: ${platform} ${arch}`);
+}
+
+const platformId = getCurrentPlatformId();
+const packageName = `@agntcy/slim-bindings-node-${platformId}`;
+
+let bindings;
+try {
+  bindings = require(packageName);
+} catch (err) {
+  if (err.code === 'MODULE_NOT_FOUND') {
+    throw new Error(
+      `Platform package ${packageName} is not installed. Install with: npm install @agntcy/slim-bindings-node (includes optional dependencies for your platform).`
+    );
+  }
+  throw err;
+}
+
+module.exports = bindings;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@agntcy/slim-bindings-node",
+  "version": "0.1.4",
+  "description": "SLIM Node.js bindings using UniFFI",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "types/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "task generate",
+    "clean": "task clean",
+    "test": "task test:integration",
+    "example:server": "task example:server",
+    "example:alice": "task example:alice"
+  },
+  "keywords": [
+    "slim",
+    "messaging",
+    "uniffi",
+    "nodejs",
+    "ffi"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agntcy/slim.git",
+    "directory": "data-plane/bindings/node"
+  },
+  "license": "Apache-2.0",
+  "optionalDependencies": {
+    "@agntcy/slim-bindings-node-darwin-arm64": "0.1.4",
+    "@agntcy/slim-bindings-node-darwin-x64": "0.1.4",
+    "@agntcy/slim-bindings-node-linux-arm64-gnu": "0.1.4",
+    "@agntcy/slim-bindings-node-linux-arm64-musl": "0.1.4",
+    "@agntcy/slim-bindings-node-linux-x64-gnu": "0.1.4",
+    "@agntcy/slim-bindings-node-linux-x64-musl": "0.1.4",
+    "@agntcy/slim-bindings-node-win32-arm64-msvc": "0.1.4",
+    "@agntcy/slim-bindings-node-win32-x64-gnu": "0.1.4",
+    "@agntcy/slim-bindings-node-win32-x64-msvc": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ffi-rs": "^1.3.0",
+    "typescript": "^5.0.0",
+    "uniffi-bindgen-react-native": "^0.29.3-1"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export * from './slim-bindings-node';