@calimero-network/agent-skills 0.1.1 → 0.3.0

package/SKILL.md

@@ -6,8 +6,9 @@ This package provides AI agent skills for building on the Calimero Network stack
 
 | Skill | Install command | When to use |
 | --- | --- | --- |
-| `calimero-rust-sdk` | `npx @calimero-network/agent-skills calimero-rust-sdk` | Building Rust WASM applications |
-| `calimero-client-js` | `npx @calimero-network/agent-skills calimero-client-js` | Frontend / Node.js clients connecting to a node |
+| `calimero-rust-sdk` | `npx @calimero-network/agent-skills calimero-rust-sdk` | Building Rust WASM applications that run on a node |
+| `calimero-sdk-js` | `npx @calimero-network/agent-skills calimero-sdk-js` | Building TypeScript/JS WASM applications that run on a node |
+| `calimero-client-js` | `npx @calimero-network/agent-skills calimero-client-js` | Browser/Node.js frontends connecting to a node (not building apps) |
 | `calimero-registry` | `npx @calimero-network/agent-skills calimero-registry` | Signing and publishing apps to the registry |
 | `calimero-desktop` | `npx @calimero-network/agent-skills calimero-desktop` | Integrating apps with Calimero Desktop SSO |
 | `calimero-node` | `npx @calimero-network/agent-skills calimero-node` | Node operators and meroctl scripting |
@@ -22,11 +23,15 @@ Skills should be loaded when the following are detected in the project:
 | Signal | Load skill |
 | --- | --- |
 | `calimero-sdk` in `Cargo.toml` | `calimero-rust-sdk` |
+| `@calimero-network/calimero-sdk-js` in `package.json` | `calimero-sdk-js` |
+| `@State` / `@Logic` decorators in TypeScript source | `calimero-sdk-js` |
+| `calimero-sdk build` in any script | `calimero-sdk-js` |
 | `@calimero-network/calimero-client` in `package.json` | `calimero-client-js` |
 | `@calimero-network/mero-js` in `package.json` | `calimero-client-js` |
 | `mero-sign` in any script or Makefile | `calimero-registry` |
 | `calimero-registry` CLI usage | `calimero-registry` |
 | `access_token` read from `window.location.hash` | `calimero-desktop` |
+| `readDesktopSSO` / `hash.get('access_token')` pattern in frontend code | `calimero-desktop` |
 | `merobox` in `package.json` or `requirements.txt` | `calimero-merobox` |
 | `calimero-client-py` in `requirements.txt` or `pyproject.toml` | `calimero-client-py` |
 | `calimero-abi-codegen` or `abi.json` in project | `calimero-abi-codegen` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@calimero-network/agent-skills",
-  "version": "0.1.1",
-  "description": "AI agent skills for Calimero Network development — Rust SDK, JS client, registry publishing, desktop SSO, and more.",
+  "version": "0.3.0",
+  "description": "AI agent skills for Calimero Network development — Rust SDK, JS SDK, JS client, registry publishing, desktop SSO, and more.",
   "keywords": [
     "calimero",
     "agent-skills",

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

@@ -1,6 +1,12 @@
 # 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/calimero-client` or `@calimero-network/mero-js`.
+
+> **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.
 
 ## Package versions
 
@@ -9,6 +15,10 @@ You are helping a developer connect a **browser or Node.js frontend** to a Calim
 | `@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.
+
 ## Critical: mero-js v2 uses camelCase
 
 v2 changed all request field names from `snake_case` to `camelCase`.
@@ -33,10 +43,53 @@ pnpm add @calimero-network/mero-js
 
 ## Core workflow
 
-1. Read auth tokens (from URL hash if opened by Desktop, otherwise prompt login)
-2. Initialize client with `node_url` + tokens
-3. Call app methods via JSON-RPC
-4. Subscribe to events via WebSocket
+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`
+
+## Minimal working example
+
+```typescript
+import {
+  rpcClient,
+  getContextId,
+  getExecutorPublicKey,
+  getAppEndpointKey,
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setContextAndIdentityFromJWT,
+  WsSubscriptionsClient,
+} from '@calimero-network/calimero-client';
+
+// 1. Store auth tokens (after SSO or login)
+setAppEndpointKey('http://localhost:2428');
+setAccessToken(accessToken);
+setRefreshToken(refreshToken);
+setContextAndIdentityFromJWT(accessToken); // extracts contextId + executorPublicKey
+
+// 2. Call an app method
+const response = await rpcClient.execute<{ key: string }, string | null>({
+  contextId: getContextId()!,
+  method: 'get',
+  argsJson: { key: 'hello' },
+  executorPublicKey: getExecutorPublicKey()!,
+});
+console.log(response.result?.output);
+
+// 3. Subscribe to real-time events
+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) {
+      console.log(e.kind, e.data);
+    }
+  }
+});
+```
 
 ## References
 

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

@@ -1,58 +1,163 @@
 # Authentication
 
-## Login flow
+## Storage helpers
+
+`@calimero-network/calimero-client` provides these storage functions (backed by `localStorage`):
 
 ```typescript
-import { setupWalletSelector } from '@near-wallet-selector/core';
-import { ClientLogin } from '@calimero-network/calimero-client';
-
-const client = new ClientLogin({ nodeUrl: 'http://localhost:2428' });
-
-// 1. Generate a client key for this device
-const { contextId, contextIdentity } = await client.generateClientKey({
-  contextId: 'your-context-id',
-  contextIdentity: 'your-identity',
-});
-
-// 2. Login — returns access_token + refresh_token
-const tokens = await client.login({
-  contextId,
-  contextIdentity,
-});
-
-// 3. Store tokens
-localStorage.setItem('access_token', tokens.access_token);
-localStorage.setItem('refresh_token', tokens.refresh_token);
+import {
+  // Node URL
+  setAppEndpointKey,
+  getAppEndpointKey,
+  // JWT tokens
+  setAccessToken,
+  getAccessToken,
+  setRefreshToken,
+  getRefreshToken,
+  // Context and identity (extracted from JWT)
+  setContextId,
+  getContextId,
+  setExecutorPublicKey,
+  getExecutorPublicKey,
+  setContextAndIdentityFromJWT,  // extracts + stores contextId + executorPublicKey from JWT
+  // App ID
+  setApplicationId,
+  getApplicationId,
+  // Auth endpoint (separate from node URL)
+  setAuthEndpointURL,
+  getAuthEndpointURL,
+  // Decoded JWT payload
+  getJWTObject,     // returns { context_id, context_identity, exp, permissions, ... }
+  // Full auth config (throws if required fields are missing)
+  getAuthConfig,    // returns { appEndpointKey, contextId, executorPublicKey, jwtToken }
+  // Logout (clears all tokens + reloads)
+  clientLogout,
+} from '@calimero-network/calimero-client';
 ```
 
-## Token storage
+---
+
+## SSO login (from Calimero Desktop — recommended path)
 
-Tokens should be stored in `localStorage` or `sessionStorage`. The client library reads
-them automatically if you use the provided storage helpers:
+When the app is opened by Desktop, tokens arrive in the URL hash. Store them:
 
 ```typescript
-import { getStorageAppEndpointKey, getJWTObject } from '@calimero-network/calimero-client';
+function initFromDesktopSSO(): boolean {
+  const hash = new URLSearchParams(window.location.hash.slice(1));
+  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 = getStorageAppEndpointKey();
-const jwt = getJWTObject();
-// jwt.access_token, jwt.refresh_token
+  if (!accessToken || !nodeUrl) return false;
+
+  // Store everything
+  setAppEndpointKey(nodeUrl);
+  setAccessToken(accessToken);
+  if (refreshToken) setRefreshToken(refreshToken);
+  if (appId) setApplicationId(appId);
+
+  // Extract contextId and executorPublicKey from JWT claims
+  setContextAndIdentityFromJWT(accessToken);
+
+  // Remove tokens from URL bar (don't let them sit in browser history)
+  history.replaceState(null, '', window.location.pathname + window.location.search);
+
+  return true;
+}
 ```
 
-## Checking auth status
+---
+
+## Manual login (no Desktop)
 
 ```typescript
-import { getJWTObject } from '@calimero-network/calimero-client';
+import { setAppEndpointKey, setAccessToken, setRefreshToken, setContextAndIdentityFromJWT } from '@calimero-network/calimero-client';
 
-function isLoggedIn(): boolean {
-  const jwt = getJWTObject();
-  return !!(jwt?.access_token);
+async function login(nodeUrl: string, accessToken: string, refreshToken: string) {
+  setAppEndpointKey(nodeUrl);
+  setAccessToken(accessToken);
+  setRefreshToken(refreshToken);
+  setContextAndIdentityFromJWT(accessToken);
 }
 ```
 
+---
+
+## Checking if authenticated
+
+```typescript
+import { getAuthConfig } from '@calimero-network/calimero-client';
+
+function isAuthenticated(): boolean {
+  const config = getAuthConfig();
+  return config.error === null;
+}
+```
+
+---
+
+## Reading the JWT payload
+
+```typescript
+import { getJWTObject } from '@calimero-network/calimero-client';
+
+const jwt = getJWTObject();
+// jwt.context_id        — the context this token is scoped to
+// jwt.context_identity  — the identity (executor public key)
+// jwt.exp               — expiry timestamp (seconds)
+// jwt.permissions       — array of permission strings
+```
+
+---
+
 ## Logout
 
 ```typescript
-localStorage.removeItem('calimero_jwt');
-localStorage.removeItem('calimero_node_url');
-// redirect to login
+import { clientLogout } from '@calimero-network/calimero-client';
+
+// Clears all tokens from localStorage and reloads the page
+clientLogout();
+```
+
+---
+
+## App startup pattern (SSO + fallback)
+
+```typescript
+import {
+  setAppEndpointKey, setAccessToken, setRefreshToken,
+  setApplicationId, setContextAndIdentityFromJWT,
+  getAuthConfig,
+} from '@calimero-network/calimero-client';
+
+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');
+
+  if (accessToken && nodeUrl) {
+    setAppEndpointKey(nodeUrl);
+    setAccessToken(accessToken);
+    const rt = hash.get('refresh_token');
+    if (rt) setRefreshToken(rt);
+    const appId = hash.get('application_id');
+    if (appId) setApplicationId(appId);
+    setContextAndIdentityFromJWT(accessToken);
+    history.replaceState(null, '', window.location.pathname);
+    renderApp();
+    return;
+  }
+
+  // Check if already authenticated from a previous session
+  const config = getAuthConfig();
+  if (config.error === null) {
+    renderApp();
+    return;
+  }
+
+  // Not authenticated — show manual login
+  renderLogin();
+}
 ```

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

@@ -2,74 +2,165 @@
 
 Calling application methods on a Calimero node.
 
-## Setup
+## The `rpcClient` singleton
+
+`@calimero-network/calimero-client` exports a pre-configured `rpcClient` singleton.
+Import it directly — do not construct `JsonRpcClient` manually.
 
 ```typescript
 import {
-  JsonRpcClient,
-  getStorageAppEndpointKey,
-  getJWTObject,
+  rpcClient,
+  getContextId,
+  getExecutorPublicKey,
 } from '@calimero-network/calimero-client';
+```
+
+---
+
+## Execute a method (mutation or view — same call)
 
-const nodeUrl = getStorageAppEndpointKey() ?? 'http://localhost:2428';
-const jwt = getJWTObject();
+```typescript
+const response = await rpcClient.execute<ArgsType, OutputType>({
+  contextId: getContextId()!,
+  method: 'methodName',
+  argsJson: { /* your args */ },
+  executorPublicKey: getExecutorPublicKey()!,
+});
 
-const client = new JsonRpcClient(nodeUrl, '/jsonrpc', jwt?.access_token);
+if (response.error) {
+  console.error(response.error.error.cause.info?.message);
+} else {
+  console.log(response.result?.output);
+}
 ```
 
+---
+
 ## Calling a mutation (changes state)
 
 ```typescript
-const response = await client.mutate<{ key: string; value: string }, void>({
-  contextId: 'your-context-id',
+const response = await rpcClient.execute<{ key: string; value: string }, void>({
+  contextId: getContextId()!,
   method: 'set',
   argsJson: { key: 'hello', value: 'world' },
-  executorPublicKey: jwt?.executor_public_key ?? '',
+  executorPublicKey: getExecutorPublicKey()!,
 });
 
 if (response.error) {
-  console.error(response.error);
+  console.error('set failed:', response.error.error.cause.info?.message);
 }
 ```
 
 ## Calling a view (read-only)
 
 ```typescript
-const response = await client.query<{ key: string }, string | null>({
-  contextId: 'your-context-id',
+const response = await rpcClient.execute<{ key: string }, string | null>({
+  contextId: getContextId()!,
   method: 'get',
   argsJson: { key: 'hello' },
-  executorPublicKey: jwt?.executor_public_key ?? '',
+  executorPublicKey: getExecutorPublicKey()!,
 });
 
-console.log(response.result?.output); // "world"
+if (!response.error) {
+  console.log(response.result?.output); // "world"
+}
 ```
 
+---
+
 ## Response shape
 
 ```typescript
-interface RpcResponse<T> {
-  result?: {
-    output: T;
-  };
-  error?: {
-    code: number;
-    message: string;
-  };
+// Success:
+{ result: { output: T } }
+
+// Error:
+{
+  error: {
+    id: number;
+    jsonrpc: string;
+    code: number;                  // HTTP-like code (400, 401, 500)
+    error: {
+      name: string;                // e.g. "FunctionCallError"
+      cause: {
+        name: string;
+        info?: { message: string };
+      };
+    };
+    headers?: Record<string, string>;
+  }
 }
 ```
 
-## Error handling
+---
+
+## Error names
+
+| 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 |
+
+---
+
+## 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:
 
 ```typescript
-const response = await client.query({ ... });
+const response = await rpcClient.execute({ ... });
 
 if (response.error) {
-  if (response.error.code === 401) {
-    // token expired — refresh and retry
-    await refreshTokens();
-    return callAgain();
+  const { code, headers } = response.error;
+  const authError = headers?.['x-auth-error'];
+
+  if (code === 401 && (authError === 'token_revoked' || authError === 'invalid_token')) {
+    // Token cannot be refreshed — send user to login
+    clientLogout();
+    return;
+  }
+
+  throw new Error(response.error.error.cause.info?.message ?? 'Unknown error');
+}
+```
+
+---
+
+## Complete example: typed wrapper
+
+```typescript
+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>({
+    contextId: getContextId()!,
+    method: 'set',
+    argsJson: { key, value },
+    executorPublicKey: getExecutorPublicKey()!,
+  });
+  if (response.error) {
+    throw new Error(response.error.error.cause.info?.message);
+  }
+}
+
+async function getItem(key: string): Promise<string | null> {
+  const response = await rpcClient.execute<{ key: string }, string | null>({
+    contextId: getContextId()!,
+    method: 'get',
+    argsJson: { key },
+    executorPublicKey: getExecutorPublicKey()!,
+  });
+  if (response.error) {
+    throw new Error(response.error.error.cause.info?.message);
   }
-  throw new Error(response.error.message);
+  return response.result?.output ?? null;
 }
 ```

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

@@ -34,18 +34,29 @@ function readSSOParams(): {
 
 ## Using SSO tokens on app startup
 
+Use the storage helpers from `@calimero-network/calimero-client`:
+
 ```typescript
+import {
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setApplicationId,
+  setContextAndIdentityFromJWT,
+} from '@calimero-network/calimero-client';
+
 async function initApp() {
   const sso = readSSOParams();
 
   if (sso.accessToken && sso.nodeUrl) {
     // Opened from Desktop — store tokens and skip login
-    localStorage.setItem('calimero_node_url', sso.nodeUrl);
-    localStorage.setItem('calimero_jwt', JSON.stringify({
-      access_token: sso.accessToken,
-      refresh_token: sso.refreshToken,
-    }));
-    // clear hash so tokens aren't in browser history
+    setAppEndpointKey(sso.nodeUrl);
+    setAccessToken(sso.accessToken);
+    if (sso.refreshToken) setRefreshToken(sso.refreshToken);
+    if (sso.applicationId) setApplicationId(sso.applicationId);
+    // Extract contextId + executorPublicKey from the JWT claims
+    setContextAndIdentityFromJWT(sso.accessToken);
+    // Clear hash so tokens aren't in browser history
     history.replaceState(null, '', window.location.pathname);
     renderApp();
   } else {
@@ -55,12 +66,6 @@ async function initApp() {
 }
 ```
 
-## calimero-client reads hash automatically
-
-If you use `@calimero-network/calimero-client`'s built-in auth helpers, the library
-reads `window.location.hash` automatically and stores the tokens. You don't need the
-manual parsing above unless you're building a custom auth flow.
-
 ## Important
 
 Always fall back to manual login if the hash params are absent — the app must work