@teneo-protocol/sdk 1.0.1 → 2.2.0

package/.eslintrc.json

@@ -13,7 +13,7 @@
     "node": true,
     "jest": true
   },
-  "ignorePatterns": ["dist", "node_modules"],
+  "ignorePatterns": ["dist", "node_modules", "examples"],
   "rules": {
     "@typescript-eslint/no-explicit-any": "warn",
     "@typescript-eslint/explicit-function-return-type": "off",
@@ -22,5 +22,14 @@
       { "argsIgnorePattern": "^_" }
     ],
     "prettier/prettier": ["error", { "trailingComma": "none" }]
-  }
+  },
+  "overrides": [
+    {
+      "files": ["**/*.test.ts", "tests/**/*.ts"],
+      "rules": {
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-unused-vars": "off"
+      }
+    }
+  ]
 }

package/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default code owners
+* @KhalilSelyan @Gradonsky @pyagmyrov

package/.github/ISSUE_TEMPLATE/01-bug.yml

@@ -0,0 +1,85 @@
+name: Bug report
+description: File a bug report for teneo-sdk
+title: "<short description of the bug>"
+labels:
+  - "bug"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report this issue and help improve teneo-sdk. We'll look into it! 🐛
+
+  - id: issue-type
+    type: dropdown
+    attributes:
+      label: Issue Type
+      description: What type of issue are you reporting?
+      options:
+        - Agent SDK Issue
+        - Network/Protocol Issue
+        - NFT Integration Issue
+        - Build/Dependency Issue
+        - Documentation Issue
+        - Other
+    validations:
+      required: true
+
+  - id: operating-system
+    type: dropdown
+    attributes:
+      label: Operating System
+      description: What operating system are you running?
+      options:
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+
+  - id: description
+    type: textarea
+    attributes:
+      label: Description of the bug
+      description: What happened and what did you expect?
+      placeholder: Describe what went wrong and what you expected to happen instead.
+    validations:
+      required: true
+
+  - id: reproduce
+    type: textarea
+    attributes:
+      label: Steps to Reproduce
+      placeholder: |
+        1. Initialize agent with configuration...
+        2. Call method/function...
+        3. See error
+    validations:
+      required: true
+
+  - id: screenshots
+    type: textarea
+    attributes:
+      label: Screenshots / Videos
+      description: If applicable, add screenshots or videos to help explain your problem
+      placeholder: Drag and drop images/videos here or paste URLs
+
+  - id: sdk-version
+    type: input
+    attributes:
+      label: SDK Version
+      description: Which version of teneo-sdk are you using? (Check your package.json or run `npm list teneo-sdk`)
+      placeholder: e.g., v0.1.0 or commit hash
+
+  - id: go-version
+    type: input
+    attributes:
+      label: Go Version
+      description: Which version of Go are you using? (Run `go version`)
+      placeholder: e.g., go1.21.0
+
+  - id: additional-context
+    type: textarea
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here (logs, error messages, etc.)
+      placeholder: Paste error messages, logs, or any other relevant information...

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Discord
+    url: https://discord.com/invite/teneoprotocol
+    about: Join our Discord for help and discussions!
+  - name: 📚 Documentation
+    url: https://teneo-protocol.ai/chat-room
+    about: Find setup guides and learn how to use Teneo SDK

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest a new feature or enhancement for teneo-sdk
+title: '[Feature Request] '
+labels: enhancement
+assignees: ''
+---
+
+What problem does this solve? (describe the problem you're experiencing)
+* 
+
+How are you working around this today? (your current solution or workaround)
+* 
+
+What's your proposed solution? (how should teneo-sdk address this?)
+* 
+
+Additional context (optional - add screenshots, examples, or other helpful details)
+* 
+
+---
+Thanks for sharing your idea! We love hearing how we can make teneo-sdk better. ✨

package/.github/workflows/claude-code-review.yml

@@ -12,11 +12,16 @@ on:
 
 jobs:
   claude-review:
+    # Only run in Teneo-Protocol organization
+    if: github.repository_owner == 'Teneo-Protocol'
+    
     # Optional: Filter by PR author
     # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    #   github.repository_owner == 'Teneo-Protocol' && (
+    #     github.event.pull_request.user.login == 'external-contributor' ||
+    #     github.event.pull_request.user.login == 'new-developer' ||
+    #     github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    #   )
     
     runs-on: ubuntu-latest
     permissions:

package/.github/workflows/claude-reviewer.yml

@@ -13,10 +13,12 @@ on:
 jobs:
   claude:
     if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      github.repository_owner == 'Teneo-Protocol' && (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      )
     runs-on: ubuntu-latest
     permissions:
       contents: read

package/.github/workflows/publish-npm.yml

@@ -1,7 +1,7 @@
 name: Publish Package
 on:
-    push:
-      branches: [main]
+  push:
+    branches: [main]
 
 permissions:
   id-token: write  # Required for OIDC
@@ -9,6 +9,7 @@ permissions:
 
 jobs:
   publish:
+    if: github.repository_owner == 'TeneoProtocolAI'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -21,7 +22,10 @@ jobs:
         with:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org'
-          cache: 'pnpm'
+
+      # Ensure npm 11.5.1 or later is installed (required for trusted publishing)
+      - name: Update npm
+        run: npm install -g npm@latest
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -32,7 +36,6 @@ jobs:
       - name: Test
         run: pnpm test
 
+      # Trusted publishing automatically adds provenance, no flags needed
       - name: Publish to npm
-        run: pnpm publish --access public --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+        run: pnpm publish --access public --no-git-checks

package/.github/workflows/push-to-main.yml

@@ -5,7 +5,7 @@ on:
   
 jobs:
   mirror-to-test-repo:
-    if: github.repository == 'Teneo-Protocol/teneo-sdk'
+    if: github.repository_owner == 'Teneo-Protocol'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Source Repo

package/.github/workflows/top-issue.yml

@@ -0,0 +1,102 @@
+name: Top Issues by Votes
+
+on:
+  schedule:
+    - cron: "0 */2 * * *"  # Run every 2 hours
+  workflow_dispatch:  # Allow manual triggering
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  update-top-issues:
+    # Only run if the repository is in the Teneo-Protocol organization
+    if: github.repository_owner == 'TeneoProtocolAI'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Update top issues list for teneo-agent-sdk
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Set this to the issue number where you want to track top issues
+          # Leave empty to skip updating (will only log)
+          ISSUE_NUMBER: "1"
+        run: |
+          #!/bin/bash
+          set -e
+
+          echo "Fetching all open issues for teneo-agent-sdk..."
+
+          # Extract owner and repo from GitHub context
+          REPO_OWNER="${{ github.repository_owner }}"
+          REPO_NAME="${{ github.event.repository.name }}"
+
+          echo "Repository: $REPO_OWNER/$REPO_NAME"
+
+          # Fetch all open issues with reaction data
+          issues=$(gh api graphql -f query='
+            query($owner: String!, $repo: String!) {
+              repository(owner: $owner, name: $repo) {
+                issues(first: 100, states: OPEN, orderBy: {field: CREATED_AT, direction: DESC}) {
+                  nodes {
+                    number
+                    title
+                    url
+                    reactions(content: THUMBS_UP) {
+                      totalCount
+                    }
+                  }
+                }
+              }
+            }
+          ' -f owner="$REPO_OWNER" -f repo="$REPO_NAME")
+
+          # Parse and sort issues by thumbs up count
+          sorted_issues=$(echo "$issues" | jq -r --arg ISSUE_NUMBER "$ISSUE_NUMBER" '
+            .data.repository.issues.nodes
+            | map(select(.number != ($ISSUE_NUMBER | tonumber)))
+            | sort_by(-.reactions.totalCount)
+            | to_entries
+            | map("\(.key + 1). [\(.value.title)](\(.value.url)) - \(.value.reactions.totalCount) 👍")
+            | join("\n")
+          ')
+
+          # Create issue body
+          current_time=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
+
+          {
+            echo "# 👍 Top Issues by Community Votes"
+            echo ""
+            echo "This list shows the most requested features and reported bugs for **teneo-agent-sdk**,"
+            echo "automatically updated every 6 hours based on 👍 reactions."
+            echo ""
+            echo "**Last updated:** $current_time"
+            echo ""
+            echo "## Top Issues"
+            echo ""
+            if [ -n "$sorted_issues" ]; then
+              echo "$sorted_issues"
+            else
+              echo "No issues found or all issues have 0 votes."
+            fi
+            echo ""
+            echo "---"
+            echo "💡 *Vote on issues by adding a 👍 reaction to help prioritize development*"
+            echo ""
+            echo "🤖 *Automatically updated by [GitHub Actions](.github/workflows/top-issue.yml)*"
+          } > /tmp/issue_body.md
+
+          # Update the tracking issue if ISSUE_NUMBER is set
+          if [ -n "$ISSUE_NUMBER" ]; then
+            echo "Updating tracking issue #$ISSUE_NUMBER..."
+            gh issue edit "$ISSUE_NUMBER" \
+              --repo "$REPO_OWNER/$REPO_NAME" \
+              --body-file /tmp/issue_body.md
+            echo "✅ Successfully updated top issues list!"
+          else
+            echo "📋 Top issues list (ISSUE_NUMBER not set, skipping update):"
+            cat /tmp/issue_body.md
+            echo ""
+            echo "💡 To enable automatic tracking, create an issue and set ISSUE_NUMBER in the workflow."
+          fi

package/CHANGELOG.md

@@ -0,0 +1,334 @@
+# Changelog
+
+All notable changes to the Teneo Protocol SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.2.0]
+
+### Quote-Approve Payment Flow
+
+Payments now use a quote-approve model. Instead of attaching payments blindly, the SDK requests a quote from the server first, then confirms with payment.
+
+### ✨ Added
+
+- **Quote-Approve Flow**
+  - `requestQuote(content, room)` - Request a quote without auto-approval
+  - `confirmQuote(taskId, options?)` - Confirm and pay for a quoted task
+  - `getPendingQuote(taskId)` - Get a pending quote by task ID
+  - New `QuoteResult` type with agent, pricing, and expiration info
+
+- **New Message Types**
+  - `request_task` - Request a task quote from coordinator
+  - `task_quote` - Server response with pricing info
+  - `confirm_task` - Confirm and execute with payment
+
+- **New Config Options**
+  - `autoApproveQuotes` - Auto-confirm quotes (default: `true`)
+  - `quoteTimeout` - Timeout for quote responses (default: `30000`ms)
+
+- **New Schemas**
+  - `PricingInfoSchema` - Agent pricing metadata
+  - `RequestTaskMessageSchema`, `TaskQuoteMessageSchema`, `ConfirmTaskMessageSchema`
+
+- **Factory Functions & Type Guards**
+  - `createRequestTask()`, `createConfirmTask()`
+  - `isTaskQuote()` type guard
+
+### 🔄 Changed
+
+- `sendMessage()` and `sendDirectCommand()` now use quote-approve flow by default
+- Payments are always enabled - removed `paymentsEnabled` config option
+- Payment client is set up automatically when `privateKey` is provided
+- `withPayments()` builder no longer has `enabled` option
+
+### 🗑️ Removed
+
+- `paymentsEnabled` config option (payments always on)
+- Legacy `validatePrice()` method (price check moved to `confirmQuote`)
+- Legacy `attachPayment()` method (handled in `confirmQuote`)
+- `setAgentRegistry()` method (no longer needed)
+
+### 📚 Documentation
+
+- Updated Payment Integration section with quote-approve examples
+- Added Manual Quote Flow documentation
+- Updated Environment Variables section
+
+---
+
+## [2.1.0] - 2025-12-08
+
+### ✨ Added
+
+#### Automatic X402 Payment Signing
+
+- SDK now auto-signs x402 payment headers when confirming tasks
+- Uses PEAQ chain with USDC stablecoin for micropayments
+- No manual payment encoding needed - just call `confirmTask({ taskId })`
+
+### 📦 Dependencies
+
+- Added `x402` library for payment signing support
+
+---
+
+## [2.0.0] - 2025-11-05
+
+### 🎉 Major Release: Multi-Room & Agent Customization
+
+Version 2.0 introduces comprehensive room management and per-room agent customization capabilities, enabling developers to create context-specific agent experiences.
+
+### ✨ Added
+
+#### Phase 1: Room Management System
+
+- **Room CRUD Operations**
+  - `createRoom(name, description?)` - Create new private rooms with validation
+  - `updateRoom(roomId, updates)` - Update room name/description (owner only)
+  - `deleteRoom(roomId)` - Delete owned rooms
+
+- **Room Query Methods**
+  - `getOwnedRooms()` - Get all rooms you created
+  - `getSharedRooms()` - Get rooms you were invited to
+  - `getAllRooms()` - Get all rooms (owned + shared) convenience method
+  - `getRoomById(roomId)` - Get specific room details
+  - `getRoomLimit()` - Check your room creation limit
+  - `canCreateRoom()` - Check if you can create more rooms
+  - `getOwnedRoomCount()` - Count your owned rooms
+
+- **Room Management Events**
+  - `room:created` - Emitted when room is created
+  - `room:updated` - Emitted when room is updated
+  - `room:deleted` - Emitted when room is deleted
+  - `room:create_error` - Emitted on creation failure
+  - `room:update_error` - Emitted on update failure
+  - `room:delete_error` - Emitted on deletion failure
+
+- **Room Management Manager**
+  - New `RoomManagementManager` class for room operations
+  - Ownership verification before CRUD operations
+  - Cached room state (owned vs shared)
+  - Room limit enforcement
+  - 6 new message handlers for room operations
+
+#### Phase 2: Agent Room Management
+
+- **Agent Room Operations**
+  - `addAgentToRoom(roomId, agentId)` - Add agent to your room (owner only)
+  - `removeAgentFromRoom(roomId, agentId)` - Remove agent from your room
+  - `listRoomAgents(roomId, useCache?)` - List agents in room with 5-min cache
+  - `listAvailableAgents(roomId, useCache?)` - List agents available to add
+
+- **Agent Room Query Methods (Synchronous)**
+  - `getRoomAgents(roomId)` - Get cached room agents instantly
+  - `getAvailableAgents(roomId)` - Get cached available agents instantly
+  - `isAgentInRoom(roomId, agentId)` - Check if agent is in room (cached)
+  - `getRoomAgentCount(roomId)` - Get agent count from cache
+
+- **Cache Management**
+  - `invalidateAgentRoomCache(roomId)` - Manually clear cache for specific room
+  - Intelligent 5-minute TTL caching for performance
+  - Automatic cache invalidation on agent add/remove
+  - Automatic cache invalidation on agent status updates
+
+- **Agent Room Events**
+  - `agent_room:agent_added` - Emitted when agent added to room
+  - `agent_room:agent_removed` - Emitted when agent removed from room
+  - `agent_room:agents_listed` - Emitted when room agents listed
+  - `agent_room:available_agents_listed` - Emitted when available agents listed
+  - `agent_room:status_update` - Real-time agent status updates
+  - `agent_room:add_error` - Emitted on agent add failure
+  - `agent_room:remove_error` - Emitted on agent remove failure
+  - `agent_room:list_error` - Emitted on list failure
+  - `agent_room:list_available_error` - Emitted on available list failure
+
+- **Agent Room Manager**
+  - New `AgentRoomManager` class for agent-room operations
+  - Ownership verification before operations
+  - Performance-optimized caching with TTL
+  - Real-time status update handling
+  - 5 new message handlers for agent room operations
+
+#### Type System Updates
+
+- Updated `RoomInfo` interface with `created_by` field (creator wallet address)
+- Fixed `Capability` schema: `type` → `name`, description now optional
+- Fixed `Command` schema: `command` → `trigger`, added `argument` field, description optional
+- Updated `AuthenticationState` with room categorization:
+  - `privateRoomIds` - Array of owned room IDs
+  - `sharedRoomIds` - Array of shared room IDs
+  - `maxPrivateRooms` - Room creation limit
+- New `AgentRoomInfo` interface for agent-room metadata
+- 26 new message types and schemas for room/agent-room operations
+
+### 📊 Testing
+
+- Added 102 new unit tests for Phase 1 and Phase 2
+- Total test count: 671 tests passing (100% pass rate)
+- Comprehensive coverage of room management
+- Comprehensive coverage of agent room management
+- All manager and handler tests passing
+
+### 🔄 Changed
+
+- Message handlers now use `BaseMessageHandler` pattern
+- Enhanced event system with 14 new event types
+- WebSocketClient now manages room and agent-room managers
+
+### 🐛 Fixed
+
+- Schema field names now match backend source of truth
+- Proper defensive copying for cache immutability
+- Validation for empty room/agent IDs
+- Proper room ownership checks before operations
+- Auth handler now correctly parses `private_rooms` array from cached authentication messages
+- Room management events now properly forward from WebSocket handlers to SDK instance
+- Room persistence: Private rooms now correctly persist after page refresh via proper initialization of RoomManagementManager from auth state
+
+### 📚 Documentation
+
+- Comprehensive README updates with v2.0 features
+- New "What's New in v2.0" section
+- Complete Room Management API documentation
+- Complete Agent Room Management API documentation
+- Updated event system documentation with all new events
+- Code examples for all new features
+- Updated test count and status
+
+### 🔐 Security
+
+- Ownership verification for all room CRUD operations
+- Ownership verification for agent-room operations
+- Validation of room and agent IDs before operations
+- Room existence checks before operations
+
+### ⚡ Performance
+
+- 5-minute cache TTL for agent room queries
+- Automatic cache invalidation on updates
+- Intelligent cache management per room
+- Defensive copying to prevent cache mutation
+- Synchronous query methods for instant cache access
+
+---
+
+## [1.0.2] - 2025-10-XX
+
+### Fixed
+
+- Minor bug fixes and improvements
+
+---
+
+## [1.0.0] - 2025-10-XX
+
+### Initial Release
+
+- WebSocket connection management
+- Ethereum wallet authentication (challenge-response)
+- Agent discovery and listing
+- Message sending to agents
+- Event-driven architecture
+- Room subscription/unsubscription
+- Webhook integration with circuit breaker
+- Retry strategies (exponential, linear, constant)
+- Message deduplication
+- Signature verification
+- Rate limiting
+- Secure private key management (AES-256-GCM encryption)
+- Comprehensive error handling
+- TypeScript support
+- 488 unit tests
+
+---
+
+## Migration Guide
+
+### Upgrading from v1.x to v2.0
+
+Version 2.0 is **backward compatible** with v1.x for basic operations. However, to take advantage of new features:
+
+#### 1. Update Package Version
+
+```bash
+pnpm install @teneo-protocol/sdk@2.0.0
+```
+
+#### 2. Room Management (New Features)
+
+**Before (v1.x):** Single room subscription
+
+```typescript
+await sdk.subscribeToRoom("room-id");
+```
+
+**After (v2.0):** Create and manage multiple rooms
+
+```typescript
+// Create your own rooms
+const room = await sdk.createRoom("My Room", "Description");
+
+// Get all your rooms
+const ownedRooms = sdk.getOwnedRooms();
+const sharedRooms = sdk.getSharedRooms();
+
+// Update/delete rooms
+await sdk.updateRoom(room.id, { name: "Updated Name" });
+await sdk.deleteRoom(room.id);
+```
+
+#### 3. Agent Customization (New Features)
+
+**New in v2.0:** Customize which agents are in each room
+
+```typescript
+// List available agents for a room
+const available = await sdk.listAvailableAgents(room.id);
+
+// Add specific agents
+await sdk.addAgentToRoom(room.id, "agent-id");
+
+// List agents in room
+const roomAgents = await sdk.listRoomAgents(room.id);
+
+// Remove agents
+await sdk.removeAgentFromRoom(room.id, "agent-id");
+```
+
+#### 4. Type Changes
+
+If you're using TypeScript and accessing agent data directly:
+
+**Capability field name changed:**
+
+```typescript
+// Before: agent.capabilities[0].type
+// After:  agent.capabilities[0].name
+```
+
+**Command field name changed:**
+
+```typescript
+// Before: agent.commands[0].command
+// After:  agent.commands[0].trigger
+```
+
+#### 5. No Breaking Changes
+
+All v1.x APIs continue to work:
+
+- ✅ `connect()`, `disconnect()`
+- ✅ `sendMessage()`
+- ✅ `subscribeToRoom()`, `unsubscribeFromRoom()`
+- ✅ `getAgents()`, `getAgent()`
+- ✅ All existing events
+
+---
+
+## Support
+
+- 📖 [Documentation](https://github.com/TeneoProtocolAI/teneo-sdk)
+- 🐛 [Issue Tracker](https://github.com/TeneoProtocolAI/teneo-sdk/issues)
+- 💬 [Discussions](https://github.com/TeneoProtocolAI/teneo-sdk/discussions)