Add HOL (Hashgraph Online) TypeScript SDK cursor rules

README.md

@@ -130,6 +130,7 @@ By creating a `.cursorrules` file in your project's root directory, you can leve
 - [Go (Basic Setup)](./rules/htmx-go-basic-cursorrules-prompt-file/.cursorrules) - Cursor rules for Go development with basic setup.
 - [Go with Fiber](./rules/htmx-go-fiber-cursorrules-prompt-file/.cursorrules) - Cursor rules for Go development with Fiber integration.
 - [Go Temporal DSL](./rules/go-temporal-dsl-prompt-file/.cursorrules) - Cursor rules for Go development with Temporal DSL integration.
+- [HOL (Hedera TypeScript SDK)](./rules/hol-hedera-typescript-cursorrules-prompt-file/.cursorrules) - Cursor rules for Hashgraph Online development with TypeScript, building AI agents on Hedera with RegistryBrokerClient.
 - [HTMX (Basic Setup)](./rules/htmx-basic-cursorrules-prompt-file/.cursorrules) - Cursor rules for HTMX development with basic setup.
 - [HTMX (Flask)](./rules/htmx-flask-cursorrules-prompt-file/.cursorrules) - Cursor rules for HTMX development with Flask integration.
 - [HTMX (Django)](./rules/htmx-django-cursorrules-prompt-file/.cursorrules) - Cursor rules for HTMX development with Django integration.

rules/hol-hedera-typescript-cursorrules-prompt-file/.cursorrules

@@ -0,0 +1,257 @@
+# Hashgraph Online (HOL) Development Rules
+
+You are an expert TypeScript developer building applications with Hashgraph Online (HOL) - the open-source SDK for AI agents and decentralized applications on Hedera.
+
+## Technology Stack
+
+**Core:**
+- Language: TypeScript (strict mode)
+- Runtime: Node.js 20+
+- Package Manager: pnpm
+- Testing: Jest with @swc/jest
+
+**HOL SDK:**
+- @hashgraphonline/standards-sdk - Core SDK for HCS standards and Registry Broker
+- @hol-org/hashnet-mcp - MCP server for AI agent integration
+
+**Frontend (when applicable):**
+- Framework: Next.js 14+ (App Router)
+- UI: shadcn/ui + Tailwind CSS
+- Icons: react-icons (Lucide preferred)
+
+## Coding Standards
+
+### TypeScript Requirements
+- NEVER use `any` - define proper interfaces
+- NEVER use `as any` casting - use type guards
+- ALWAYS define explicit return types
+- ALWAYS use generics for flexible code
+- Validate external data with type guards or zod
+
+### File Naming
+- Use kebab-case: `registry-client.ts`, `topic-manager.ts`
+- Test files: `__tests__/registry-client.test.ts`
+- Components: `registry-browser.tsx`
+
+### Code Style
+- Max 500 lines per file - split larger files
+- No nested ternaries
+- No inline comments - use JSDoc only
+- No console.log - use Logger from standards-sdk
+- Prettier formatting required
+
+### React Patterns (when applicable)
+- NO render functions like `renderContent()`
+- NO inline callbacks in JSX
+- NO hooks in loops/conditionals
+- ALWAYS use separate child components
+- ALWAYS define Props interfaces
+
+## HOL SDK Usage
+
+### RegistryBrokerClient - Initialization
+```typescript
+import { RegistryBrokerClient } from '@hashgraphonline/standards-sdk';
+
+const client = new RegistryBrokerClient({
+  baseUrl: 'https://api.hol.org',
+  apiKey: process.env.HOL_API_KEY,
+});
+```
+
+### RegistryBrokerClient - Search Agents
+```typescript
+import { RegistryBrokerClient, SearchParams, Logger } from '@hashgraphonline/standards-sdk';
+
+const logger = new Logger({ module: 'AgentSearch', level: 'info' });
+const client = new RegistryBrokerClient();
+
+const searchParams: SearchParams = {
+  q: 'weather',
+  registry: 'hcs-10',
+  limit: 10,
+  page: 1,
+};
+
+const results = await client.search(searchParams);
+logger.info('Search completed', { total: results.total });
+results.hits.forEach(agent => {
+  logger.debug('Agent found', { name: agent.name, description: agent.description });
+});
+```
+
+### RegistryBrokerClient - Resolve Agent (UAID)
+```typescript
+import { RegistryBrokerClient, Logger } from '@hashgraphonline/standards-sdk';
+
+const client = new RegistryBrokerClient();
+const logger = new Logger({ module: 'AgentResolver', level: 'info' });
+
+const agent = await client.resolveUaid('hcs10://0.0.123456/agent-name');
+logger.info('Agent resolved', { 
+  name: agent.name, 
+  protocols: agent.protocols, 
+  capabilities: agent.capabilities 
+});
+```
+
+### RegistryBrokerClient - Register Agent
+```typescript
+import { RegistryBrokerClient, AgentRegistrationRequest, Logger } from '@hashgraphonline/standards-sdk';
+
+const client = new RegistryBrokerClient();
+const logger = new Logger({ module: 'AgentRegistration', level: 'info' });
+
+const registration: AgentRegistrationRequest = {
+  name: 'My Agent',
+  description: 'A helpful AI agent',
+  protocols: ['hcs-10'],
+  capabilities: ['chat', 'search'],
+  endpoint: 'https://my-agent.example.com',
+};
+
+const response = await client.registerAgent(registration, {
+  autoTopUp: {
+    accountId: process.env.HEDERA_OPERATOR_ID!,
+    privateKey: process.env.HEDERA_OPERATOR_KEY!,
+  },
+});
+
+if (response.success) {
+  logger.info('Agent registered', { uaid: response.uaid });
+}
+```
+
+### RegistryBrokerClient - Chat with Agent
+```typescript
+import { RegistryBrokerClient, StartChatOptions, Logger } from '@hashgraphonline/standards-sdk';
+
+const client = new RegistryBrokerClient();
+const logger = new Logger({ module: 'AgentChat', level: 'info' });
+
+const options: StartChatOptions = {
+  uaid: 'hcs10://0.0.123456/agent-name',
+  auth: {
+    accountId: process.env.HEDERA_OPERATOR_ID!,
+    privateKey: process.env.HEDERA_OPERATOR_KEY!,
+  },
+};
+
+const conversation = await client.chat.start(options);
+
+const response = await conversation.send({
+  plaintext: 'Hello, can you help me?',
+});
+
+logger.info('Agent response received', { sessionId: conversation.sessionId });
+```
+
+### RegistryBrokerClient - Get Stats
+```typescript
+import { RegistryBrokerClient, Logger } from '@hashgraphonline/standards-sdk';
+
+const client = new RegistryBrokerClient();
+const logger = new Logger({ module: 'RegistryStats', level: 'info' });
+
+const stats = await client.stats();
+logger.info('Registry stats', { totalAgents: stats.totalAgents, protocols: stats.protocols });
+
+const registries = await client.registries();
+registries.forEach(r => logger.debug('Registry', { name: r.name }));
+```
+
+### RegistryBrokerClient - Vector Search
+```typescript
+import { RegistryBrokerClient, VectorSearchRequest, Logger } from '@hashgraphonline/standards-sdk';
+
+const client = new RegistryBrokerClient();
+const logger = new Logger({ module: 'VectorSearch', level: 'info' });
+
+const request: VectorSearchRequest = {
+  query: 'find me an agent that can help with weather forecasts',
+  limit: 5,
+  filter: {
+    registry: 'hcs-10',
+    protocols: ['a2a'],
+  },
+};
+
+const results = await client.vectorSearch(request);
+results.hits.forEach(hit => {
+  logger.info('Match found', { name: hit.agent.name, score: hit.score });
+});
+```
+
+## Testing Requirements
+
+### TDD Workflow
+1. RED: Write failing tests first
+2. GREEN: Implement minimum code to pass
+3. REFACTOR: Improve while keeping tests green
+
+### Test Structure
+```typescript
+describe('RegistryBrokerClient', () => {
+  let client: RegistryBrokerClient;
+
+  beforeEach(() => {
+    client = new RegistryBrokerClient();
+  });
+
+  describe('search', () => {
+    it('should return agents matching query', async () => {
+      const result = await client.search({ q: 'test' });
+
+      expect(result.hits).toBeDefined();
+      expect(Array.isArray(result.hits)).toBe(true);
+    });
+  });
+
+  describe('resolveUaid', () => {
+    it('should resolve valid UAID', async () => {
+      const agent = await client.resolveUaid('hcs10://0.0.123456/test');
+
+      expect(agent.name).toBeDefined();
+    });
+  });
+});
+```
+
+### Test Commands
+```bash
+pnpm test                    # Run all tests
+pnpm test -- --watch         # Watch mode
+pnpm test -- --coverage      # Coverage report
+pnpm test -- -t "pattern"    # Run specific tests
+```
+
+## Validation Checklist
+
+Before completing any task:
+1. `pnpm run lint` - Zero violations
+2. `pnpm run typecheck` - Zero errors  
+3. `pnpm run build` - Must compile
+4. `pnpm test` - All tests pass
+
+## Environment Configuration
+
+```typescript
+import 'dotenv/config';
+
+const config = {
+  baseUrl: process.env.HOL_API_URL || 'https://api.hol.org',
+  apiKey: process.env.HOL_API_KEY,
+  network: process.env.HEDERA_NETWORK || 'testnet',
+  operatorId: process.env.HEDERA_OPERATOR_ID,
+  operatorKey: process.env.HEDERA_OPERATOR_KEY,
+};
+```
+
+## Resources
+
+- HOL Website: https://hol.org
+- HOL Registry: https://hol.org/registry
+- SDK Docs: https://hol.org/docs/libraries/standards-sdk/overview/
+- Registry Broker Client: https://hol.org/docs/libraries/standards-sdk/registry-broker-client/
+- GitHub: https://github.com/hashgraph-online
+- NPM: @hashgraphonline/standards-sdk