@calimero-network/agent-skills 0.2.0 → 0.4.0

package/skills/calimero-abi-codegen/references/generated-output.md

@@ -2,7 +2,7 @@
 
 Running `calimero-abi-codegen -i abi.json -o src/generated --client-name KvStoreClient` produces:
 
-```
+```text
 src/generated/
 ├── types.ts
 └── KvStoreClient.ts
@@ -36,7 +36,10 @@ import { CalimeroApp, Context } from '@calimero-network/calimero-client';
 import type { Entry } from './types';
 
 export class KvStoreClient {
-  constructor(private app: CalimeroApp, private context: Context) {}
+  constructor(
+    private app: CalimeroApp,
+    private context: Context
+  ) {}
 
   async set(key: string, value: string): Promise<void> {
     await this.app.mutate(this.context, 'set', { key, value });
@@ -55,7 +58,12 @@ export class KvStoreClient {
 ## Using the generated client
 
 ```typescript
-import { CalimeroApp, Context, getJWTObject, getStorageAppEndpointKey } from '@calimero-network/calimero-client';
+import {
+  CalimeroApp,
+  Context,
+  getJWTObject,
+  getStorageAppEndpointKey,
+} from '@calimero-network/calimero-client';
 import { KvStoreClient } from './generated/KvStoreClient';
 
 const app = new CalimeroApp(getStorageAppEndpointKey(), getJWTObject()?.access_token);
@@ -65,7 +73,7 @@ const client = new KvStoreClient(app, context);
 // Fully typed — IDE autocomplete works
 await client.set('hello', 'world');
 const value = await client.get('hello'); // string | null
-const all = await client.entries();      // Entry[]
+const all = await client.entries(); // Entry[]
 ```
 
 ## Regenerating after app changes

package/skills/calimero-abi-codegen/rules/schema-version.md

@@ -1,19 +1,24 @@
 # Rule: ABI manifest must have schema_version "wasm-abi/1"
 
-The codegen tool rejects any ABI file that doesn't have the exact string `"wasm-abi/1"` as its `schema_version`.
+The codegen tool rejects any ABI file that doesn't have the exact string `"wasm-abi/1"` as its
+`schema_version`.
 
 ## WRONG:
 
 ```json
 {
   "schema_version": "1",
-  "types": {}, "methods": [], "events": []
+  "types": {},
+  "methods": [],
+  "events": []
 }
 ```
 
 ```json
 {
-  "types": {}, "methods": [], "events": []
+  "types": {},
+  "methods": [],
+  "events": []
 }
 ```
 
@@ -22,7 +27,9 @@ The codegen tool rejects any ABI file that doesn't have the exact string `"wasm-
 ```json
 {
   "schema_version": "wasm-abi/1",
-  "types": {}, "methods": [], "events": []
+  "types": {},
+  "methods": [],
+  "events": []
 }
 ```
 

package/skills/calimero-abi-codegen/rules/unique-names.md

@@ -20,9 +20,7 @@ The ABI validator rejects manifests where names clash — across methods, events
   "types": {
     "set": { "kind": "record", "fields": [] }
   },
-  "methods": [
-    { "name": "set", "params": [] }
-  ]
+  "methods": [{ "name": "set", "params": [] }]
 }
 ```
 
@@ -43,9 +41,7 @@ Map keys **must** be `{ "kind": "string" }`.
 ```json
 {
   "types": {},
-  "methods": [
-    { "name": "get", "returns": { "$ref": "NonExistentType" } }
-  ]
+  "methods": [{ "name": "get", "returns": { "$ref": "NonExistentType" } }]
 }
 ```
 

package/skills/calimero-client-js/SKILL.md

@@ -1,44 +1,135 @@
 # calimero-client-js — Agent Instructions
 
-You are helping a developer connect a **browser or Node.js frontend** to a Calimero node using `@calimero-network/calimero-client` or `@calimero-network/mero-js`.
+You are helping a developer connect a **browser or Node.js frontend** to a Calimero node using
+`@calimero-network/mero-react` (preferred) or `@calimero-network/calimero-client`.
+
+> **NOT this skill** if the developer is building the application logic that _runs on the node_ in
+> TypeScript — that is `calimero-sdk-js`. This skill is for the _client_ side: auth, RPC calls, and
+> WebSocket subscriptions from a browser or React app.
 
 ## Package versions
 
-| Package | Version | Notes |
-| --- | --- | --- |
-| `@calimero-network/calimero-client` | latest | Stable client for browser/Node — auth, RPC, WebSocket |
-| `@calimero-network/mero-js` | `>=2.0.0-beta.1` | v2 API — all request fields are **camelCase** |
+| Package                             | Notes                                                                                     |
+| ----------------------------------- | ----------------------------------------------------------------------------------------- |
+| `@calimero-network/mero-react`      | **Preferred for React apps.** Exports `MeroJs`, `useSubscription`, `MeroProvider`, hooks. |
+| `@calimero-network/mero-js`         | Core SDK. Zero deps. Used standalone in non-React contexts.                               |
+| `@calimero-network/calimero-client` | Legacy client. Still works; new projects should prefer mero-react/mero-js.                |
 
 ## Critical: mero-js v2 uses camelCase
 
-v2 changed all request field names from `snake_case` to `camelCase`.
+All request field names changed from `snake_case` to `camelCase` in v2.
 
 ```typescript
-// WRONG (v1 / old):
+// WRONG (v1):
 { context_id: '...', context_identity: '...' }
 
-// CORRECT (v2):
+// CORRECT (v2 / mero-react):
 { contextId: '...', contextIdentity: '...' }
 ```
 
-This applies to `GenerateClientKeyRequest` and all other request types.
+## React app pattern (mero-react) — recommended
 
-## Install
+### Install
 
 ```bash
-pnpm add @calimero-network/calimero-client
-# or
-pnpm add @calimero-network/mero-js
+pnpm add @calimero-network/mero-react
 ```
 
-## Core workflow
+### Setup provider
+
+```tsx
+import { MeroProvider } from '@calimero-network/mero-react';
+
+function App() {
+  return (
+    <MeroProvider nodeUrl="http://localhost:2428">
+      <YourApp />
+    </MeroProvider>
+  );
+}
+```
 
-1. On startup: read SSO tokens from URL hash (if opened by Desktop), otherwise check `localStorage` for existing session, otherwise show login
-2. Store tokens using the provided storage helpers (`setAppEndpointKey`, `setAccessToken`, etc.)
-3. Call app methods via the `rpcClient` singleton using `rpcClient.execute()`
-4. Subscribe to events via `WsSubscriptionsClient`
+### Call app methods
 
-## Minimal working example
+Generated clients (from abi-codegen) import `MeroJs` from `@calimero-network/mero-react`:
+
+```typescript
+import { MeroJs } from '@calimero-network/mero-react';
+
+export class KvClient {
+  constructor(
+    private mero: MeroJs,
+    private contextId: string,
+    private executorPublicKey: string
+  ) {}
+
+  async set(key: string, value: string): Promise<void> {
+    await this.mero.rpc.execute({
+      contextId: this.contextId,
+      method: 'set',
+      argsJson: { key, value },
+      executorPublicKey: this.executorPublicKey,
+    });
+  }
+
+  async get(key: string): Promise<string | null> {
+    const response = await this.mero.rpc.execute({
+      contextId: this.contextId,
+      method: 'get',
+      argsJson: { key },
+      executorPublicKey: this.executorPublicKey,
+    });
+    return response as string | null;
+  }
+}
+```
+
+### Subscribe to events (mero-react hook)
+
+```typescript
+import { useSubscription } from '@calimero-network/mero-react';
+
+// Subscribe to one or more contexts
+useSubscription([contextId], (event: { contextId: string; data: unknown }) => {
+  // event.data may be:
+  // - { type: 'EventName', ...payload } for direct events
+  // - { events: [{ kind: string, data: unknown }] } for execution event batches
+  console.log('event:', event.data);
+});
+
+// Subscribe to multiple contexts (e.g. game + lobby simultaneously)
+useSubscription([gameContextId, lobbyContextId], (event) => {
+  console.log('from context:', event.contextId);
+});
+```
+
+### Parsing execution event payloads
+
+Events from `app::emit!()` arrive batched in an `events` array. Each entry has `kind` (the variant
+name) and `data` (the payload, possibly as a byte array):
+
+```typescript
+function decodeEventData(data: unknown): unknown {
+  // If data is a number array, it's JSON-encoded bytes
+  if (Array.isArray(data) && data.every((n) => typeof n === 'number')) {
+    return JSON.parse(new TextDecoder().decode(new Uint8Array(data)));
+  }
+  return data;
+}
+
+// In the subscription callback:
+useSubscription([contextId], (event) => {
+  const payload = event.data as any;
+  if (Array.isArray(payload?.events)) {
+    for (const e of payload.events) {
+      const decoded = decodeEventData(e.data);
+      console.log(e.kind, decoded); // e.g. "Inserted", { key: "...", value: "..." }
+    }
+  }
+});
+```
+
+## Legacy calimero-client pattern
 
 ```typescript
 import {
@@ -68,7 +159,7 @@ const response = await rpcClient.execute<{ key: string }, string | null>({
 });
 console.log(response.result?.output);
 
-// 3. Subscribe to real-time events
+// 3. Subscribe to events
 const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
 await ws.connect();
 ws.subscribe([getContextId()!]);
@@ -81,7 +172,21 @@ ws.addCallback((event) => {
 });
 ```
 
+## Core workflow
+
+1. On startup: read SSO tokens from URL hash (if opened by Desktop), otherwise check `localStorage`,
+   otherwise show login
+2. Store tokens using storage helpers or the `MeroProvider` (handles this automatically)
+3. Call app methods via the generated typed client or `mero.rpc.execute()`
+4. Subscribe to events via `useSubscription` (React) or `WsSubscriptionsClient`
+
+## Related skills
+
+- **`calimero-core`** — JSON-RPC protocol spec, WebSocket event schemas, context/app/identity model
+- **`calimero-desktop`** — SSO token passing from Calimero Desktop (URL hash flow)
+- **`calimero-node`** — node setup if the developer is also running the node
+
 ## References
 
-See `references/` for auth flow, RPC calls, WebSocket events, and SSO.
-See `rules/` for camelCase API and token refresh requirements.
+See `references/` for auth flow, RPC calls, WebSocket events, and SSO. See `rules/` for camelCase
+API and token refresh requirements.

package/skills/calimero-client-js/references/auth.md

@@ -19,7 +19,7 @@ import {
   getContextId,
   setExecutorPublicKey,
   getExecutorPublicKey,
-  setContextAndIdentityFromJWT,  // extracts + stores contextId + executorPublicKey from JWT
+  setContextAndIdentityFromJWT, // extracts + stores contextId + executorPublicKey from JWT
   // App ID
   setApplicationId,
   getApplicationId,
@@ -27,9 +27,9 @@ import {
   setAuthEndpointURL,
   getAuthEndpointURL,
   // Decoded JWT payload
-  getJWTObject,     // returns { context_id, context_identity, exp, permissions, ... }
+  getJWTObject, // returns { context_id, context_identity, exp, permissions, ... }
   // Full auth config (throws if required fields are missing)
-  getAuthConfig,    // returns { appEndpointKey, contextId, executorPublicKey, jwtToken }
+  getAuthConfig, // returns { appEndpointKey, contextId, executorPublicKey, jwtToken }
   // Logout (clears all tokens + reloads)
   clientLogout,
 } from '@calimero-network/calimero-client';
@@ -44,10 +44,10 @@ When the app is opened by Desktop, tokens arrive in the URL hash. Store them:
 ```typescript
 function initFromDesktopSSO(): boolean {
   const hash = new URLSearchParams(window.location.hash.slice(1));
-  const accessToken  = hash.get('access_token');
+  const accessToken = hash.get('access_token');
   const refreshToken = hash.get('refresh_token');
-  const nodeUrl      = hash.get('node_url');
-  const appId        = hash.get('application_id');
+  const nodeUrl = hash.get('node_url');
+  const appId = hash.get('application_id');
 
   if (!accessToken || !nodeUrl) return false;
 
@@ -72,7 +72,12 @@ function initFromDesktopSSO(): boolean {
 ## Manual login (no Desktop)
 
 ```typescript
-import { setAppEndpointKey, setAccessToken, setRefreshToken, setContextAndIdentityFromJWT } from '@calimero-network/calimero-client';
+import {
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setContextAndIdentityFromJWT,
+} from '@calimero-network/calimero-client';
 
 async function login(nodeUrl: string, accessToken: string, refreshToken: string) {
   setAppEndpointKey(nodeUrl);
@@ -126,8 +131,11 @@ clientLogout();
 
 ```typescript
 import {
-  setAppEndpointKey, setAccessToken, setRefreshToken,
-  setApplicationId, setContextAndIdentityFromJWT,
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setApplicationId,
+  setContextAndIdentityFromJWT,
   getAuthConfig,
 } from '@calimero-network/calimero-client';
 
@@ -135,7 +143,7 @@ async function bootstrap() {
   // Try SSO from Desktop hash
   const hash = new URLSearchParams(window.location.hash.slice(1));
   const accessToken = hash.get('access_token');
-  const nodeUrl     = hash.get('node_url');
+  const nodeUrl = hash.get('node_url');
 
   if (accessToken && nodeUrl) {
     setAppEndpointKey(nodeUrl);

package/skills/calimero-client-js/references/rpc-calls.md

@@ -4,15 +4,11 @@ Calling application methods on a Calimero node.
 
 ## The `rpcClient` singleton
 
-`@calimero-network/calimero-client` exports a pre-configured `rpcClient` singleton.
-Import it directly — do not construct `JsonRpcClient` manually.
+`@calimero-network/calimero-client` exports a pre-configured `rpcClient` singleton. Import it
+directly — do not construct `JsonRpcClient` manually.
 
 ```typescript
-import {
-  rpcClient,
-  getContextId,
-  getExecutorPublicKey,
-} from '@calimero-network/calimero-client';
+import { rpcClient, getContextId, getExecutorPublicKey } from '@calimero-network/calimero-client';
 ```
 
 ---
@@ -23,7 +19,9 @@ import {
 const response = await rpcClient.execute<ArgsType, OutputType>({
   contextId: getContextId()!,
   method: 'methodName',
-  argsJson: { /* your args */ },
+  argsJson: {
+    /* your args */
+  },
   executorPublicKey: getExecutorPublicKey()!,
 });
 
@@ -96,20 +94,20 @@ if (!response.error) {
 
 ## Error names
 
-| name | meaning |
-|---|---|
-| `FunctionCallError` | App method returned an error |
-| `RpcExecutionError` | Node couldn't execute the method |
+| name                  | meaning                                            |
+| --------------------- | -------------------------------------------------- |
+| `FunctionCallError`   | App method returned an error                       |
+| `RpcExecutionError`   | Node couldn't execute the method                   |
 | `InvalidRequestError` | Malformed request (wrong context-id, missing args) |
-| `AuthenticationError` | JWT expired, revoked, or missing |
-| `UnknownServerError` | Unexpected server error |
+| `AuthenticationError` | JWT expired, revoked, or missing                   |
+| `UnknownServerError`  | Unexpected server error                            |
 
 ---
 
 ## Error handling with 401
 
-The HTTP client inside `rpcClient` automatically refreshes tokens on `401 token_expired`.
-For `token_revoked` or `invalid_token` you need to re-authenticate:
+The HTTP client inside `rpcClient` automatically refreshes tokens on `401 token_expired`. For
+`token_revoked` or `invalid_token` you need to re-authenticate:
 
 ```typescript
 const response = await rpcClient.execute({ ... });
@@ -133,11 +131,7 @@ if (response.error) {
 ## Complete example: typed wrapper
 
 ```typescript
-import {
-  rpcClient,
-  getContextId,
-  getExecutorPublicKey,
-} from '@calimero-network/calimero-client';
+import { rpcClient, getContextId, getExecutorPublicKey } from '@calimero-network/calimero-client';
 
 async function setItem(key: string, value: string): Promise<void> {
   const response = await rpcClient.execute<{ key: string; value: string }, void>({

package/skills/calimero-client-js/references/sso.md

@@ -1,15 +1,15 @@
 # SSO — Calimero Desktop Integration
 
-When a user opens your app from Calimero Desktop, auth tokens are passed via the URL hash.
-Reading them lets users skip the manual login flow entirely.
+When a user opens your app from Calimero Desktop, auth tokens are passed via the URL hash. Reading
+them lets users skip the manual login flow entirely.
 
 ## Hash parameters
 
-| Parameter | Description |
-| --- | --- |
-| `access_token` | JWT for authenticated node calls |
-| `refresh_token` | Token to obtain a new access token |
-| `node_url` | URL of the local node to connect to |
+| Parameter        | Description                                |
+| ---------------- | ------------------------------------------ |
+| `access_token`   | JWT for authenticated node calls           |
+| `refresh_token`  | Token to obtain a new access token         |
+| `node_url`       | URL of the local node to connect to        |
 | `application_id` | The installed application's ID on the node |
 
 ## Reading from hash
@@ -68,5 +68,5 @@ async function initApp() {
 
 ## Important
 
-Always fall back to manual login if the hash params are absent — the app must work
-when opened directly in a browser, not only from Desktop.
+Always fall back to manual login if the hash params are absent — the app must work when opened
+directly in a browser, not only from Desktop.

package/skills/calimero-client-js/references/websocket-events.md

@@ -6,111 +6,117 @@ Subscribe to real-time events emitted by the application running on the node.
 
 The node sends two kinds of events to subscribers:
 
-| type | when | payload |
-|---|---|---|
-| `StateMutation` | Another member mutated shared state | `{ newRoot: string }` |
-| `ExecutionEvent` | App emitted `app::emit!()` | `{ events: ExecutionEvent[] }` |
+| type             | when                                | payload                        |
+| ---------------- | ----------------------------------- | ------------------------------ |
+| `StateMutation`  | Another member mutated shared state | `{ newRoot: string }`          |
+| `ExecutionEvent` | App emitted `app::emit!()`          | `{ events: ExecutionEvent[] }` |
 
-An `ExecutionEvent` has: `{ kind: string; data: any }` where `kind` matches the Rust event variant name.
+An `ExecutionEvent` entry: `{ kind: string; data: any }` where `kind` matches the Rust event variant
+name and `data` may be a byte array (UTF-8 JSON) or a plain object.
 
 ---
 
-## Connect and subscribe
+## mero-react: useSubscription hook (preferred for React)
 
 ```typescript
-import {
-  WsSubscriptionsClient,
-  getAppEndpointKey,
-  getContextId,
-} from '@calimero-network/calimero-client';
+import { useSubscription } from '@calimero-network/mero-react';
+
+function MyComponent({ contextId }: { contextId: string }) {
+  useSubscription([contextId], (event: { contextId: string; data: unknown }) => {
+    const payload = event.data as any;
+
+    // ExecutionEvent: data has an `events` array
+    if (Array.isArray(payload?.events)) {
+      for (const e of payload.events) {
+        const data = decodeEventData(e.data);
+        switch (e.kind) {
+          case 'Inserted':
+            console.log('inserted', data);
+            break;
+          case 'Removed':
+            console.log('removed', data);
+            break;
+        }
+      }
+    }
+  });
+}
+
+// Byte-array payloads are JSON-encoded; decode them:
+function decodeEventData(data: unknown): unknown {
+  if (Array.isArray(data) && data.every((n) => typeof n === 'number')) {
+    try {
+      return JSON.parse(new TextDecoder().decode(new Uint8Array(data)));
+    } catch {
+      return data;
+    }
+  }
+  return data;
+}
+```
 
-const nodeUrl = getAppEndpointKey()!;
-const ws = new WsSubscriptionsClient(nodeUrl, '/ws');
+## Subscribe to multiple contexts
 
-// Connect first, then subscribe and add callback
-await ws.connect();
-ws.subscribe([getContextId()!]);
-ws.addCallback((event) => {
-  console.log('Event received:', event);
+```typescript
+// Subscribe to game context + lobby context simultaneously
+useSubscription([gameContextId, lobbyContextId], (event) => {
+  console.log('event from context:', event.contextId);
 });
 ```
 
 ---
 
-## Handling ExecutionEvents from app logic
+## Legacy calimero-client: WsSubscriptionsClient
 
 ```typescript
-import type {
-  NodeEvent,
-  ExecutionEventPayload,
-  StateMutationPayload,
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
 } from '@calimero-network/calimero-client';
 
-ws.addCallback((event: NodeEvent) => {
+const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
+await ws.connect();
+ws.subscribe([getContextId()!]);
+ws.addCallback((event) => {
   if (event.type === 'ExecutionEvent') {
     for (const e of event.data.events) {
-      // e.kind matches the Rust event variant name, e.g. 'ItemAdded'
-      // e.data contains the event payload
-      switch (e.kind) {
-        case 'ItemAdded':
-          console.log('Item added:', e.data);
-          addItemToUI(e.data.key, e.data.value);
-          break;
-        case 'ItemRemoved':
-          removeItemFromUI(e.data.key);
-          break;
-      }
+      console.log(e.kind, e.data);
     }
   }
-
   if (event.type === 'StateMutation') {
-    // Another member changed shared state — refresh data from node
-    console.log('State root changed:', event.data.newRoot);
     refreshDataFromNode();
   }
 });
 ```
 
----
-
-## Subscribe to multiple contexts
-
-```typescript
-ws.subscribe([contextId1, contextId2]);
-// Events include event.contextId to identify which context emitted them
-```
-
----
-
-## Cleanup
+Cleanup:
 
 ```typescript
-// Remove a specific callback
 ws.removeCallback(myCallback);
-
-// Unsubscribe from specific contexts
 ws.unsubscribe([contextId]);
-
-// Close connection entirely
 ws.disconnect();
 ```
 
 ---
 
-## React hook pattern
+## React hook for legacy client
 
 ```typescript
 import { useEffect } from 'react';
-import { WsSubscriptionsClient, getAppEndpointKey, getContextId } from '@calimero-network/calimero-client';
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
+} from '@calimero-network/calimero-client';
 
-function useNodeEvents(onEvent: (event: NodeEvent) => void) {
+function useNodeEvents(onEvent: (event: any) => void) {
   useEffect(() => {
     const nodeUrl = getAppEndpointKey();
     const contextId = getContextId();
     if (!nodeUrl || !contextId) return;
 
     const ws = new WsSubscriptionsClient(nodeUrl, '/ws');
-
     ws.connect().then(() => {
       ws.subscribe([contextId]);
       ws.addCallback(onEvent);
@@ -124,3 +130,11 @@ function useNodeEvents(onEvent: (event: NodeEvent) => void) {
   }, [onEvent]);
 }
 ```
+
+---
+
+## Connection notes
+
+- `WsSubscriptionsClient` does **not** reconnect automatically — handle reconnect manually
+- `useSubscription` from `mero-react` manages the connection lifecycle for you
+- WebSocket tokens are **not** auto-refreshed unlike `rpcClient` HTTP calls