Skip to content

Node.js SDK

The SLIM Node.js SDK (@agntcy/slim-bindings) provides a TypeScript-friendly API for building applications on SLIM. Bindings are generated from the same Rust core as every other language binding via UniFFI, with native ESM modules and optional platform-specific native addons published to npm.

Requirements
Runtime Node.js 18 or higher
Package @agntcy/slim-bindings on npm
Module format Native ESM (import only — require() is not supported)
Examples node/examples in slim-bindings

npm installs this package and, when published for your OS/arch, the matching optional native addon (@agntcy/slim-bindings-*). Full TypeScript types ship under types/ in the published package.

Installation

npm install @agntcy/slim-bindings

yarn add @agntcy/slim-bindings

pnpm add @agntcy/slim-bindings

Getting Started

The SDK tutorials build a full application step by step — initialising the service, connecting to a node, creating an app, opening sessions, receiving messages, and adding persistence — with Node.js snippets shown alongside every other binding.

Start with Connecting to SLIM.

API Overview

Type Description
Default export Static entry point for initialisation and global service access
Service Manages connections and creates apps
App Application handle for sessions, subscriptions, and routing
Session Session for sending and receiving messages
Name Identity in org/namespace/app format
ReceivedMessage Received message with payload (bytes) and context metadata
SessionConfig Session configuration (type, MLS, retries)
ClientConfig Client connection configuration (endpoint, TLS, transport auth)
ServerConfig Server listen configuration (endpoint, TLS, transport auth)
OidcConfig OIDC transport authentication settings
OidcPolicyConfig Claim-based access policy (Cel, Rego, RegoFile)

Type notes

64-bit values (like the connection ID from connectAsync) are real bigint end to end — pass them through as-is rather than converting to Number. Enum-typed fields (like SessionConfig.sessionType) are real TypeScript enums (SessionType.PointToPoint), not string literals.

Session Configuration

const sessionConfig: slimBindings.SessionConfig = {
  sessionType: slimBindings.SessionType.PointToPoint,
  metadata: new Map(),
  mlsSettings: { headerIntegrityValidationPercent: 100 },
};

const session = await app.createSessionAndWaitAsync(sessionConfig, remoteName);

Annotate the object as SessionConfig rather than leaving it inferred — that is what catches an unknown field, which is otherwise accepted and silently ignored. metadata is required, maxRetries and interval fall back to the SLIM defaults, and omitting mlsSettings disables MLS.

Transport Authentication

Separate from the app identity passed to createAppWithSecret, the gRPC connection to a SLIM node can carry its own credentials via config.auth.

OIDC (client credentials)

const config = slimBindings.newInsecureClientConfig('http://127.0.0.1:46357');
config.auth = new slimBindings.ClientAuthenticationConfig.Oidc({
  config: {
    issuerUrl: 'https://auth.example.com',
    clientId: 'my-client',
    clientSecret: 's3cr3t',
    scope: 'openid profile',
    timeout: 30_000,  // durations are milliseconds
  },
});

const connId = await service.connectAsync(config);

For the refresh-token flow, set refreshToken (or refreshTokenFile, which is rewritten in place as tokens rotate) instead of clientSecret.

OIDC (server verification)

const config = slimBindings.newInsecureServerConfig('0.0.0.0:46357');
config.auth = new slimBindings.ServerAuthenticationConfig.Oidc({
  config: {
    issuerUrl: 'https://auth.example.com',
    audience: 'slim',
    jwksTtl: 3_600_000,
    policy: new slimBindings.OidcPolicyConfig.Cel({
      expression: '"admin" in claims.groups',
    }),
  },
});

await service.runServerAsync(config);

policy accepts OidcPolicyConfig.Cel, OidcPolicyConfig.Rego (which must define package slim.auth with default allow = false), or OidcPolicyConfig.RegoFile.

JSON configuration

newConfigFromJson accepts a full gRPC client config covering TLS material, backoff, and every authentication mode:

{
  "endpoint": "http://127.0.0.1:46357",
  "tls": { "insecure": true },
  "auth": {
    "type": "oidc",
    "issuer_url": "https://auth.example.com",
    "client_id": "my-client",
    "client_secret": "s3cr3t",
    "audience": "slim",
    "policy": { "cel": "\"admin\" in claims.groups" }
  }
}

The schema matches the client configuration schema in the slim repository.

SLIMRPC

The Node.js SDK includes SLIMRPC support for Protobuf-based RPC over SLIM. Install the protoc-gen-slimrpc-node plugin and add it to your buf.gen.yaml alongside the standard protobuf-es plugin. See the SLIMRPC Compiler and the Serving and Client tutorials.

Examples

The slim-bindings/node directory includes complete working examples:

Example Description
examples/point-to-point-alice.ts 1:1 messaging receiver
examples/point-to-point-bob.ts 1:1 messaging sender
examples/group.ts Group sessions with moderator/participant roles
examples/slimrpc/simple Protobuf RPC over SLIM

Point-to-point:

cd node
task example:alice   # Receiver
task example:bob     # Sender (in another terminal)

SLIMRPC (requires a running SLIM node and generated proto code):

task example:slimrpc:server
task example:slimrpc:client

Platform Support

Platform Architecture Status
Linux x86_64 Supported
Linux aarch64 Supported
macOS x86_64 Supported
macOS aarch64 (Apple Silicon) Supported
Windows x86_64 Supported

If install fails with a native-load error, your platform/version combination may not have a published binary yet. Build from source or check the node README for maintainer instructions.

Building from Source

To build the Node.js SDK from the slim-bindings repository:

git clone https://github.com/agntcy/slim-bindings
cd slim-bindings/node

npm install
task generate
task build
task test

See README_dev.md for generator setup, Task commands, and publishing.

Next Steps