@calimero-network/agent-skills 0.2.0 → 0.4.0

package/skills/calimero-sdk-js/references/collections.md

@@ -0,0 +1,132 @@
+# CRDT Collections
+
+All persistent state in a `calimero-sdk-js` app must use CRDT types from
+`@calimero-network/calimero-sdk-js/collections`.
+
+## Counter (G-Counter)
+
+Distributed counting. The value is the sum across all contributing nodes.
+
+```typescript
+import { Counter } from '@calimero-network/calimero-sdk-js/collections';
+
+const counter = new Counter();
+counter.increment(); // +1
+counter.incrementBy(5n); // +5 (bigint)
+const total = counter.value(); // bigint
+```
+
+> Counter values are always `bigint`. Do not compare with `=== 0` — use `=== 0n`.
+
+## UnorderedMap\<K, V\>
+
+Key-value store with Last-Write-Wins conflict resolution per key.
+
+```typescript
+import { UnorderedMap } from '@calimero-network/calimero-sdk-js/collections';
+
+const map = new UnorderedMap<string, string>();
+map.set('key', 'value');
+const val = map.get('key'); // 'value' | undefined
+const exists = map.has('key'); // boolean
+map.remove('key');
+const all = map.entries(); // [['key', 'value'], ...]
+```
+
+## UnorderedSet\<T\>
+
+Set of unique values with Last-Write-Wins per element.
+
+```typescript
+import { UnorderedSet } from '@calimero-network/calimero-sdk-js/collections';
+
+const set = new UnorderedSet<string>();
+set.add('item'); // true on first insert, false if already present
+set.has('item'); // true
+set.delete('item');
+const items = set.toArray();
+```
+
+## Vector\<T\>
+
+Ordered list. Conflicts resolved by position.
+
+```typescript
+import { Vector } from '@calimero-network/calimero-sdk-js/collections';
+
+const vec = new Vector<string>();
+vec.push('first');
+vec.push('second');
+const item = vec.get(0); // 'first'
+const last = vec.pop(); // 'second'
+const len = vec.len(); // 1 (bigint)
+```
+
+## LwwRegister\<T\>
+
+Holds a single value. Last write wins based on timestamp.
+
+```typescript
+import { LwwRegister } from '@calimero-network/calimero-sdk-js/collections';
+
+const reg = new LwwRegister<string>();
+reg.set('current value');
+const current = reg.get(); // 'current value' | undefined
+```
+
+## UserStorage
+
+User-owned signed data. Writes are verified by the owner's signature.
+
+```typescript
+import { UserStorage } from '@calimero-network/calimero-sdk-js/collections';
+
+const storage = new UserStorage<string>();
+storage.set(executorId, 'my value');
+const val = storage.get(executorId);
+```
+
+## FrozenStorage
+
+Immutable, content-addressed storage. Write once; content never changes.
+
+```typescript
+import { FrozenStorage } from '@calimero-network/calimero-sdk-js/collections';
+
+const frozen = new FrozenStorage<string>();
+const id = frozen.store('immutable content');
+const val = frozen.get(id);
+```
+
+## Nested collections
+
+Nested structures propagate changes automatically — no manual re-serialization needed.
+
+```typescript
+// Map<projectId, Set<tags>> — just works
+const projectTags = new UnorderedMap<string, UnorderedSet<string>>();
+
+const tags = new UnorderedSet<string>();
+tags.add('urgent');
+projectTags.set('proj:123', tags);
+
+// Modifying the inner set propagates automatically
+projectTags.get('proj:123')?.add('high-priority');
+```
+
+## State field initialization
+
+CRDT fields must be initialized inline in the `@State` class:
+
+```typescript
+@State
+export class AppState {
+  // ✅ Inline initialization
+  items: UnorderedMap<string, string> = new UnorderedMap();
+  count: Counter = new Counter();
+
+  // ❌ Never use plain JS types for state
+  // plainMap: Map<string, string> = new Map();
+  // array: string[] = [];
+}
+```

package/skills/calimero-sdk-js/references/events.md

@@ -0,0 +1,63 @@
+# Events
+
+Events let your app push real-time notifications to all context members. They are emitted during
+mutation methods and received by clients via WebSocket.
+
+## Emitting events
+
+```typescript
+import { emit, emitWithHandler } from '@calimero-network/calimero-sdk-js';
+
+// Simple event — clients receive it and dispatch themselves
+emit({ type: 'ItemAdded', key: 'foo', value: 'bar' });
+
+// Event with a named handler — clients call `onItemAdded(event)` if defined
+emitWithHandler({ type: 'ItemAdded', key: 'foo' }, 'onItemAdded');
+```
+
+Events can only be emitted inside mutation methods (not `@View()` methods).
+
+## Receiving events on the client
+
+Clients use `WsSubscriptionsClient` from `@calimero-network/calimero-client`:
+
+```typescript
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
+} from '@calimero-network/calimero-client';
+
+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 `type` field from emit()
+      // e.data — the rest of the emitted object
+      console.log(e.kind, e.data);
+    }
+  }
+});
+```
+
+## Event typing (recommended)
+
+Define a discriminated union to type your events:
+
+```typescript
+type AppEvent =
+  | { type: 'ItemAdded'; key: string; value: string }
+  | { type: 'ItemRemoved'; key: string };
+
+// Emit
+emit({ type: 'ItemAdded', key: 'foo', value: 'bar' } satisfies AppEvent);
+```
+
+## Important
+
+- Events are best-effort — clients may miss them if disconnected
+- Do not rely on events for state consistency — use RPC calls to query current state
+- Emitting from a `@View()` method is not supported

package/skills/calimero-sdk-js/rules/crdt-only-state.md

@@ -0,0 +1,47 @@
+# Rule: All @State fields must be CRDT types
+
+Every field on a `@State` class must be a CRDT collection from
+`@calimero-network/calimero-sdk-js/collections`. Plain JavaScript types are not persisted or
+synchronized.
+
+## WRONG — plain JS types in state:
+
+```typescript
+@State
+export class AppState {
+  items: Map<string, string> = new Map(); // ✗ — not a CRDT, not synced
+  tags: string[] = []; // ✗ — not a CRDT, not synced
+  name: string = ''; // ✗ — use LwwRegister instead
+  count: number = 0; // ✗ — use Counter instead
+}
+```
+
+## CORRECT — CRDT types:
+
+```typescript
+@State
+export class AppState {
+  items: UnorderedMap<string, string> = new UnorderedMap();
+  tags: UnorderedSet<string> = new UnorderedSet();
+  name: LwwRegister<string> = new LwwRegister();
+  count: Counter = new Counter();
+}
+```
+
+## Why this matters
+
+Plain JS types are not serialized to the node's CRDT storage. State that uses `Map`, `Set`, `Array`,
+or primitives directly will be lost on the next call and will never sync to other nodes in the
+context.
+
+## Choosing the right CRDT
+
+| Data shape                | Use                  |
+| ------------------------- | -------------------- |
+| Counting (monotonic)      | `Counter`            |
+| Key-value lookup          | `UnorderedMap<K, V>` |
+| Unique membership         | `UnorderedSet<T>`    |
+| Ordered list              | `Vector<T>`          |
+| Single value (overwrites) | `LwwRegister<T>`     |
+| User-owned signed data    | `UserStorage<T>`     |
+| Immutable content         | `FrozenStorage<T>`   |

package/skills/calimero-sdk-js/rules/no-console-log.md

@@ -0,0 +1,38 @@
+# Rule: Use env.log() — not console.log()
+
+`console` is not available in the QuickJS/WASM runtime. Calling `console.log()` will throw a runtime
+error. Use `env.log()` from the SDK's env module instead.
+
+## WRONG:
+
+```typescript
+console.log('Processing item:', key); // ✗ — throws at runtime
+console.error('Something went wrong'); // ✗ — throws at runtime
+```
+
+## CORRECT:
+
+```typescript
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+env.log(`Processing item: ${key}`); // ✓ — output appears in node logs
+env.log(`Error: ${error}`); // ✓
+```
+
+## env.log() format
+
+`env.log()` accepts a single string. Use template literals for dynamic values:
+
+```typescript
+env.log(`set called: key=${key}, value=${value}`);
+env.log(`counter is now ${this.count.value()}`);
+```
+
+## Other env utilities
+
+```typescript
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+// Get the calling executor's public key (Uint8Array, 32 bytes)
+const executorId = env.executorId();
+```

package/skills/calimero-sdk-js/rules/view-decorator.md

@@ -0,0 +1,48 @@
+# Rule: @View() is required on read-only methods
+
+Every method that does not modify state must be decorated with `@View()`. Without it, the runtime
+will persist state after every call — even when nothing changed — causing unnecessary storage writes
+and cross-node syncs.
+
+## WRONG — read-only method without @View():
+
+```typescript
+@Logic(AppState)
+export class AppLogic extends AppState {
+  // ✗ — no @View(), triggers persistence on every call
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+
+  // ✗ — returning a count without @View()
+  getCount(): bigint {
+    return this.count.value();
+  }
+}
+```
+
+## CORRECT:
+
+```typescript
+@Logic(AppState)
+export class AppLogic extends AppState {
+  @View()
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+
+  @View()
+  getCount(): bigint {
+    return this.count.value();
+  }
+}
+```
+
+## How to tell if a method needs @View()
+
+A method is read-only if it:
+
+- Does not call any mutation methods on CRDT fields (`set`, `insert`, `add`, `push`, `increment`,
+  etc.)
+- Does not call `emit()` or `emitWithHandler()`
+- Only reads values and returns results