Getting Started

Install, connect, and make your first API call in minutes

Installation

npm

npm install @calimero-network/mero-js

pnpm

pnpm add @calimero-network/mero-js

yarn

yarn add @calimero-network/mero-js

Requires Node.js 18+ or any modern browser. Zero runtime dependencies — built on the Fetch API and Web Streams.

Basic Example — Username & Password Auth

Create an SDK instance

import { MeroJs } from '@calimero-network/mero-js';

const sdk = new MeroJs({
baseUrl: 'http://localhost:2428',
timeoutMs: 10_000, // optional, default 10s
});

Authenticate

// Authenticate with username and password
await sdk.authenticate({
username: 'admin',
password: 'your-password',
});

// Check auth state
console.log(sdk.isAuthenticated()); // true

List contexts

const res = await sdk.admin.getContexts();
console.log(res.data); // Context[]

Execute a WASM method

const result = await sdk.rpc.execute{<{ value: string }>}({
  contextId: 'ctx-id-here',
  method: 'get_value',
  argsJson: { key: 'hello' },
});
console.log(result);

Clean up

// Close SSE/WS connections when done
sdk.close();

SSO — Receiving Tokens from URL Hash

When your app is opened from Calimero Desktop, tokens arrive in window.location.hash. Use parseAuthCallback() to read them and sdk.setTokenData() to apply them:

import { MeroJs, parseAuthCallback } from '@calimero-network/mero-js';

const auth = parseAuthCallback(window.location.hash);

if (auth) {
  // auth.nodeUrl, auth.accessToken, auth.refreshToken
  // auth.applicationId, auth.contextId, auth.contextIdentity
  const sdk = new MeroJs({ baseUrl: auth.nodeUrl });
  sdk.setTokenData({
    access_token: auth.accessToken,
    refresh_token: auth.refreshToken,
    expires_at: 0, // parsed from JWT automatically
  });
  // Remove tokens from URL bar (security best practice)
  history.replaceState(null, '', location.pathname);
}

The hash fragment format is: #access_token=...&refresh_token=...&node_url=...&application_id=...&context_id=...&context_identity=...

Token Persistence

Pass a tokenStore to automatically persist and restore tokens across page loads:

import { MeroJs, LocalStorageTokenStore } from '@calimero-network/mero-js';

const sdk = new MeroJs({
baseUrl: 'http://localhost:2428',
tokenStore: new LocalStorageTokenStore('my-app-tokens'),
});

// On next page load, tokens are restored automatically.
// sdk.isAuthenticated() returns true if valid tokens exist.

Error Handling

import { HTTPError, RpcError } from '@calimero-network/mero-js';

try {
  const result = await sdk.rpc.execute({ ... });
} catch (err) {
  if (err instanceof RpcError) {
    console.error(`RPC error ${err.code}: ${err.message}`);
  } else if (err instanceof HTTPError) {
    console.error(`HTTP ${err.status}: ${err.statusText}`);
  } else if (err.name === 'AbortError') {
    console.log('Request timed out or was cancelled');
  }
}

See Error Model for full details.