Implement TS SDK workspace provider methods (configureProvider, getProviders, updateProvider)

[Hyperkit-dev]

🎯 Layer 1: Intent Parsing

What needs to be done?

Task Title:

Implement TS SDK workspace provider methods (configureProvider, getProviders, updateProvider)

Primary Goal:

Successfully implement TS SDK workspace provider methods (configureProvider, getProviders, updateProvider) with full functionality

User Story / Context:

As a developer/user, I want to implement TS SDK workspace provider methods (configureProvider, getProviders, updateProvider) so that HyperAgent functions as designed

Business Impact:

Contributes to Phase 1 Foundation goals and enables multi-tenant workspace provider management as specified in the platform blueprint

Task Metadata:

• Sprint: Sprint 2
• Related Epic/Project: GitHub Project 9 - Phase 1 Foundation
• Issue Type: Feature
• Area: Sdk-Cli
• Related Documentation:
  • Platform Blueprint - Section 2: Agent model and pipeline
  • Scope Definition - MVP Scope: Sprint 3-4
  • Execution Strategy - Section 1: Implementation Strategy
  • Business Model - Pillar 1: HyperAgent Cloud (SaaS)

---

📚 Layer 2: Knowledge Retrieval

What information do I need?

Required Skills / Knowledge:

• Frontend (React/Next.js, TS)
• Backend/API (FastAPI, Python)

Estimated Effort:

M (Medium - 3-5 days)

Knowledge Resources:

• Review .cursor/skills/ for relevant patterns
• Check .cursor/llm/ for implementation examples
• Read Platform Blueprint: docs/draft.md
• Read Scope Definition: docs/planning/3-Scope-Definition.md
• Read Execution Strategy: docs/reference/spec/execute.md
• Study tech docs / ADRs in docs/adrs/ directory
• Review API / schema references for relevant services

Architecture Context:

According to the Platform Blueprint, HyperAgent uses a microservice architecture with three major layers:

1. Client Shells (Web app, Desktop app, CLI)
2. Orchestration/Agents (Python/FastAPI + LangGraph)
3. Core Services (Project service, data/memory layer, blockchain gateway)

This task implements SDK methods for workspace provider management, which is part of the multi-tenant workspace model described in the Business Model.

Code Examples & Patterns:
TypeScript SDK Example:

import { HyperAgentClient } from '@hyperagent/sdk';

const client = new HyperAgentClient({
  apiUrl: process.env.API_URL,
  apiKey: process.env.API_KEY
});

// Create workspace
const workspace = await client.createWorkspace({
  name: "My Workspace"
});

// Configure provider
await client.configureProvider({
  workspaceId: workspace.id,
  providerType: "llm",
  providerName: "anthropic",
  config: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
});

// Get providers
const providers = await client.getProviders({
  workspaceId: workspace.id
});

// Update provider
await client.updateProvider({
  workspaceId: workspace.id,
  providerId: providers[0].id,
  config: {
    apiKey: process.env.NEW_ANTHROPIC_API_KEY
  }
});

---

⚠️ Layer 3: Constraint Analysis

What constraints and dependencies exist?

Known Dependencies:

• Workspace provider schema must be designed (see issue Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) #273)
• Backend API endpoints for provider management must be implemented

Technical Constraints:

Scope limited to TypeScript SDK implementation. Backend API changes tracked separately.

Current Blockers:

None identified (update as work progresses)

Risk Assessment & Mitigations:

Standard development risks; follow best practices, code review, and testing. Ensure proper encryption handling for sensitive provider keys.

Resource Constraints:

• Deadline: Feb 18–Mar 2 (Sprint 2)
• Effort Estimate: M (Medium - 3-5 days)

---

💡 Layer 4: Solution Generation

How should this be implemented?

Solution Approach:

Implement three SDK methods in libs/sdk-ts/src/workspace.ts:

1. configureProvider() - Create or update a provider configuration
2. getProviders() - List all providers for a workspace
3. updateProvider() - Update an existing provider configuration

Methods should handle encryption/decryption of sensitive keys, proper error handling, and type safety.

Design Considerations:

• Follow established patterns from .cursor/skills/
• Maintain consistency with existing SDK codebase
• Consider scalability and maintainability
• Ensure proper error handling and validation
• Plan for testing and validation
• Align with multi-tenant workspace model from Business Model

Acceptance Criteria (Solution Validation):

• configureProvider() method implemented and tested
• getProviders() method implemented and tested
• updateProvider() method implemented and tested
• Proper TypeScript types defined for provider configurations
• Error handling for invalid workspace IDs, provider types
• Unit tests written with 80%+ coverage
• Integration tests with backend API
• Documentation updated in SDK README
• Code reviewed and approved

---

📋 Layer 5: Execution Planning

What are the concrete steps?

Implementation Steps:

1. Review workspace provider schema design from issue Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) #273
2. Define TypeScript interfaces for provider configurations
3. Implement configureProvider() method
4. Implement getProviders() method
5. Implement updateProvider() method
6. Write unit tests for all three methods
7. Write integration tests with backend API
8. Update SDK documentation
9. Code review and approval
10. Demo in sprint review and gather feedback

Environment Setup:
Repos / Services:

• SDK repo: libs/sdk-ts/
• Backend repo: services/orchestrator/

Required Environment Variables:

• DATABASE_URL= (get from internal vault)
• REDIS_URL= (get from internal vault)
• X402_GATEWAY_URL= (get from internal vault)
• X402_API_KEY= (get from internal vault)

Access & Credentials:

• API keys: Internal vault (1Password / Doppler)
• Access request: Contact @devops or project lead

---

✅ Layer 6: Output Formatting & Validation

How do we ensure quality delivery?

Ownership & Collaboration:

• Owner: @ArhonJay
• Reviewer: @JustineDevs
• Access Request: @JustineDevs or @ArhonJay
• Deadline: Feb 18–Mar 2
• Communication: Daily stand-up updates, GitHub issue comments

Quality Gates:

• Code follows project style guide
• All tests pass (unit, integration, e2e)
• No critical lint/security issues
• Documentation updated (README, code comments, ADRs)
• Meets all acceptance criteria
• TypeScript strict mode compliance
• SDK published to npm (if applicable)

Review Checklist:

• Code review approved by @JustineDevs
• CI/CD pipeline passes
• Performance benchmarks met (if applicable)
• Security scan passes
• SDK documentation updated

Delivery Status:

• Initial Status: To Do
• Progress Tracking: Use issue comments for updates
• Sign-off: Approved by @Hyperionkit on 2026-02-06
• PR Link: [Link to merged PR(s)]

Related Issues:

• Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) #273: Design workspace_providers table schema
• Implement workspace provider resolver (resolve LLM keys, Tenderly, RPC from workspace_providers table) #274: Implement workspace provider resolver
• Implement Workspace Settings UI (Providers tab: LLM keys, Tenderly, RPC endpoints) #275: Implement Workspace Settings UI

Documentation References:

• Platform Blueprint
• Scope Definition
• Execution Strategy
• Business Model
• Project Phases