@calimero-network/agent-skills 0.3.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,54 +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` (`@calimero-network/calimero-sdk-js`).
-> This skill is for the *client* side: auth, RPC calls, and WebSocket subscriptions from
-> a browser or backend service.
+> **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** |
-
-**Which to use:** new projects should prefer `@calimero-network/mero-js` v2. If you are
-maintaining an existing codebase that uses `calimero-client`, check for snake_case field
-names before migrating — do not mix both packages in the same project.
+| 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 {
@@ -78,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()!]);
@@ -91,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.