OmniRoute/.omo/deepseek-web-integration/ISSUE_PROPOSALS.md

DeepSeek Web Wrapper Integration - Issue Proposals

Overview

DeepSeek web integration following the established web-wrapper pattern from Claude, ChatGPT, Perplexity, and Grok implementations. This document outlines 5 GitHub issues to be created sequentially.

---

Issue #1: Research & Discovery - DeepSeek Web API Mapping

Title: [Research] DeepSeek Web API Mapping & Authentication Flow

Type: Research/Investigation

Priority: High

Assignee: @[developer]

Description:

Objective

Map DeepSeek's web interface API endpoints, authentication mechanism, and request/response formats to enable web-based integration.

Scope

• Identify all API endpoints used by https://chat.deepseek.com
• Document authentication flow (session cookies, tokens, headers)
• Capture request/response payload structures
• Identify model identifiers and parameters
• Document SSE response format and message structure
• Identify rate limiting and timeout behaviors
• Map UUID/ID requirements (conversation, user, organization)

Deliverables

1. API Endpoint Mapping (Markdown table)

   • Endpoint URL
   • HTTP Method
   • Purpose
   • Required headers
   • Request payload structure
   • Response format

2. Authentication Flow Diagram

   • Session establishment
   • Cookie/token requirements
   • Device ID handling
   • Refresh mechanisms

3. Request/Response Examples

   • Raw HTTP requests (curl format)
   • Complete request payloads (JSON)
   • Complete response payloads (SSE format)
   • Error responses

4. Critical Parameters

   • Model identifiers (deepseek-chat, deepseek-coder, etc.)
   • Required headers (User-Agent, Accept, Content-Type)
   • Timezone/locale handling
   • Tool/function calling format (if supported)

5. Comparison Matrix

   • How DeepSeek differs from Claude, ChatGPT, Perplexity
   • Unique requirements or limitations
   • Compatibility with existing executor pattern

Success Criteria

• ✅ All endpoints documented with examples
• ✅ Authentication flow fully understood
• ✅ No gaps in request/response structure
• ✅ Comparison with existing implementations complete
• ✅ Approved by code review before proceeding to implementation

Timeline

• Estimated: 0.5-1 day
• Blocker: Must complete before Issue #2

Notes

• Use browser DevTools (Network tab) to capture real requests
• Test with multiple message types (text, code, long responses)
• Document any rate limiting or session timeout behaviors
• Identify any Cloudflare/anti-bot protections

---

Issue #2: Implementation - DeepSeek Web Executor

Title: [Implementation] DeepSeek Web Executor & Middleware

Type: Feature

Priority: High

Depends On: Issue #1 (Research complete)

Description:

Objective

Implement DeepSeekWebExecutor following the established pattern from existing web executors (Claude, ChatGPT, Perplexity, Grok).

Scope

Phase 1: Core Executor (Days 1-3)

• Create src/open-sse/executors/deepseek-web.ts
• Implement session/cookie management
• Implement request payload construction
• Implement SSE response parsing
• Implement error handling and retry logic
• Implement model parameter mapping

Phase 2: Middleware & Integration (Days 3-5)

• Create src/open-sse/middleware/deepseek-web.ts
• Implement OpenAI format → DeepSeek format translation
• Implement response streaming
• Implement token counting (if applicable)
• Add to executor registry

Phase 3: Auto-Refresh Variant (Days 5-7)

• Create src/open-sse/executors/deepseek-web-with-auto-refresh.ts
• Implement session refresh mechanism
• Implement credential rotation
• Add cache management

Code Structure

// deepseek-web.ts
export class DeepSeekWebExecutor extends BaseExecutor {
  async execute(input: ExecuteInput): Promise<AsyncIterable<string>>;
  private async getSessionToken(): Promise<string>;
  private async buildRequestPayload(input: ExecuteInput): Promise<object>;
  private async parseSSEResponse(response: Response): Promise<AsyncIterable<string>>;
  private mapOpenAIToDeepSeek(input: ExecuteInput): object;
  private mapDeepSeekToOpenAI(response: object): object;
}

// middleware/deepseek-web.ts
export const deepseekWebMiddleware = (executor: DeepSeekWebExecutor) => {
  // Format translation
  // Error handling
  // Response streaming
};

Key Implementation Details

1. Session Management

   • Extract session cookie from credentials
   • Validate session freshness
   • Handle session expiration

2. Request Payload

   • Map OpenAI format to DeepSeek format
   • Include all required headers
   • Handle model selection
   • Support tool/function calling (if available)

3. Response Streaming

   • Parse SSE format correctly
   • Extract message content
   • Handle metadata/usage tokens
   • Implement proper error propagation

4. Error Handling

   • Network timeouts (120s default)
   • Invalid session (refresh or error)
   • Rate limiting (exponential backoff)
   • Malformed responses
   • Model not found

Testing Requirements

• Unit tests for payload mapping
• Unit tests for response parsing
• Integration tests with mock responses
• E2E tests with real session (if safe)
• Error scenario tests (all 6 critical bugs)

Success Criteria

• ✅ All endpoints working
• ✅ Streaming responses working
• ✅ Error handling complete
• ✅ Tests passing (>80% coverage)
• ✅ No security vulnerabilities (Snyk)
• ✅ Code review approved

Timeline

• Estimated: 5-10 days
• Blocker: Issue #1 complete

Files to Create

• src/open-sse/executors/deepseek-web.ts (~400 lines)
• src/open-sse/executors/deepseek-web-with-auto-refresh.ts (~300 lines)
• src/open-sse/middleware/deepseek-web.ts (~200 lines)
• src/open-sse/executors/__tests__/deepseek-web.test.ts (~500 lines)

Dependencies

• Existing: BaseExecutor, ExecuteInput, AsyncIterable<string>
• External: playwright (for session management if needed)

---

Issue #3: Testing & Validation - DeepSeek Web Executor

Title: [Testing] DeepSeek Web Executor - Unit, Integration & E2E Tests

Type: Testing

Priority: High

Depends On: Issue #2 (Implementation complete)

Description:

Objective

Comprehensive test coverage for DeepSeek web executor ensuring reliability, security, and correctness.

Scope

Unit Tests (Days 1-2)

• Payload mapping tests (OpenAI → DeepSeek)
• Response parsing tests (SSE format)
• Error handling tests (all 6 critical bugs)
• Session management tests
• Header construction tests
• Model parameter mapping tests

Integration Tests (Days 2-3)

• Mock API response tests
• Streaming response tests
• Error recovery tests
• Timeout handling tests
• Rate limiting tests

E2E Tests (Days 3-4)

• Real session tests (if credentials available)
• Multi-turn conversation tests
• Tool/function calling tests (if supported)
• Long response handling tests
• Concurrent request tests

Performance Tests (Days 4-5)

• Response time benchmarks
• Memory usage under load
• Concurrent request handling
• Token counting accuracy

Test Templates

// Unit test example
describe("DeepSeekWebExecutor", () => {
  describe("mapOpenAIToDeepSeek", () => {
    test("should map basic message correctly", () => {
      const input = { messages: [{ role: "user", content: "hello" }] };
      const result = executor.mapOpenAIToDeepSeek(input);
      expect(result).toHaveProperty("prompt");
      expect(result.model).toBe("deepseek-chat");
    });
  });

  describe("parseSSEResponse", () => {
    test("should parse valid SSE stream", async () => {
      const response = createMockSSEResponse();
      const chunks = await executor.parseSSEResponse(response);
      expect(chunks).toHaveLength(3);
    });
  });

  describe("error handling", () => {
    test("should handle invalid session", async () => {
      // Test session expiration
    });
    test("should handle rate limiting", async () => {
      // Test 429 response
    });
    test("should handle network timeout", async () => {
      // Test 120s timeout
    });
  });
});

Critical Bugs to Test

1. Cookie Format Mismatch - Ensure all cookie formats handled
2. UUID Resolution - Validate UUID extraction and usage
3. SSE Parsing - Handle malformed SSE responses
4. Session Expiration - Proper refresh mechanism
5. Rate Limiting - Exponential backoff implementation
6. Timeout Handling - 120s timeout enforcement

Coverage Requirements

• Minimum: 80% code coverage
• Target: 90% code coverage
• Critical paths: 100% coverage

Success Criteria

• ✅ All tests passing
• ✅ Coverage >80%
• ✅ No flaky tests
• ✅ Performance benchmarks met
• ✅ Security tests passing (Snyk)

Timeline

• Estimated: 5-10 days
• Blocker: Issue #2 complete

Files to Create/Modify

• src/open-sse/executors/__tests__/deepseek-web.test.ts (~800 lines)
• src/open-sse/middleware/__tests__/deepseek-web.test.ts (~400 lines)
• src/open-sse/__tests__/e2e/deepseek-web.e2e.ts (~300 lines)

---

Issue #4: Documentation & Examples - DeepSeek Web Integration

Title: [Documentation] DeepSeek Web Integration - Setup & Examples

Type: Documentation

Priority: Medium

Depends On: Issue #2 (Implementation complete)

Description:

Objective

Comprehensive documentation for DeepSeek web integration including setup, usage, and troubleshooting.

Scope

Setup Guide

• Prerequisites (Node.js, dependencies)
• Installation steps
• Credential setup (session cookie extraction)
• Configuration options
• Environment variables

API Documentation

• Executor interface
• Middleware options
• Error handling
• Rate limiting
• Timeout configuration

Usage Examples

• Basic message completion
• Streaming responses
• Tool/function calling (if supported)
• Error handling patterns
• Session refresh patterns

Troubleshooting Guide

• Common errors and solutions
• Session expiration handling
• Rate limiting recovery
• Network timeout debugging
• Cookie format issues

Comparison Guide

• DeepSeek vs Claude Web
• DeepSeek vs ChatGPT Web
• Feature matrix
• Performance comparison
• Cost comparison

Files to Create

• docs/integrations/deepseek-web/README.md
• docs/integrations/deepseek-web/SETUP.md
• docs/integrations/deepseek-web/API.md
• docs/integrations/deepseek-web/EXAMPLES.md
• docs/integrations/deepseek-web/TROUBLESHOOTING.md

Success Criteria

• ✅ All sections complete
• ✅ Examples tested and working
• ✅ Clear and concise language
• ✅ Proper formatting and structure

Timeline

• Estimated: 2-3 days

---

Issue #5: Release & Integration - DeepSeek Web Executor

Title: [Release] DeepSeek Web Executor - Integration & Deployment

Type: Release

Priority: High

Depends On: Issues #2, #3, #4 complete

Description:

Objective

Integrate DeepSeek web executor into main codebase and prepare for production release.

Scope

Code Integration (Days 1-2)

• Add executor to registry
• Add middleware to router
• Update type definitions
• Update exports
• Add to provider list

Quality Assurance (Days 2-3)

• Run full test suite
• Security scan (Snyk)
• Code coverage check (>80%)
• Performance benchmarks
• Integration tests

Release Preparation (Days 3-4)

• Update CHANGELOG.md
• Update README.md (provider list)
• Create release notes
• Tag version
• Update documentation site

Deployment (Days 4-5)

• Merge to main branch
• Deploy to staging
• Deploy to production
• Monitor for issues
• Post-deployment validation

Checklist

Code Quality

• ✅ All tests passing
• ✅ Coverage >80%
• ✅ No linting errors
• ✅ No TypeScript errors
• ✅ No security vulnerabilities

Documentation

• ✅ README updated
• ✅ API docs complete
• ✅ Examples working
• ✅ Troubleshooting guide complete
• ✅ CHANGELOG updated

Testing

• ✅ Unit tests passing
• ✅ Integration tests passing
• ✅ E2E tests passing
• ✅ Performance benchmarks met
• ✅ Security tests passing

Deployment

• ✅ Staging deployment successful
• ✅ Production deployment successful
• ✅ Monitoring alerts configured
• ✅ Rollback plan ready
• ✅ Post-deployment validation complete

Success Criteria

• ✅ DeepSeek executor available in production
• ✅ Zero critical issues
• ✅ Documentation complete
• ✅ Performance meets SLA

Timeline

• Estimated: 1-2 days
• Blocker: All previous issues complete

---

Implementation Timeline Summary

Phase	Issue	Duration	Effort	Priority
1. Research	#1	0.5-1 day	1 FTE	High
2. Implementation	#2	5-10 days	1 FTE	High
3. Testing	#3	5-10 days	1 FTE	High
4. Documentation	#4	2-3 days	1 FTE	Medium
5. Release	#5	1-2 days	1 FTE	High
TOTAL		14-26 days	1 FTE	High

---

Critical Success Factors

DO ✅

• Follow the 5-phase approach sequentially
• Complete research before implementation
• Write tests alongside implementation
• Document as you build
• Get code review at each phase
• Test with real DeepSeek session
• Monitor production deployment

DON'T ❌

• Skip research phase
• Implement without understanding API
• Write code without tests
• Deploy without documentation
• Ignore error handling
• Hardcode credentials
• Skip security review

---

Risk Mitigation

Risk	Probability	Impact	Mitigation
API changes	Medium	High	Monitor API docs, add version detection
Session expiration	High	Medium	Implement auto-refresh, proper error handling
Rate limiting	Medium	Medium	Implement exponential backoff, queue
Cloudflare protection	Low	High	Use Playwright for session management
Breaking changes	Low	High	Maintain backward compatibility

---

Related PRs & Issues

• PR #2283 - Claude Web Executor (reference implementation)
• Issue #[X] - ChatGPT Web Integration
• Issue #[Y] - Perplexity Web Integration
• Issue #[Z] - Grok Web Integration

---

Approval & Sign-off

Created: [Date] Proposed by: [Developer] Reviewed by: [Code Owner] Status: Ready for implementation

---

Next Steps

1. Create GitHub issues from this proposal
2. Assign to developer
3. Start with Issue #1 (Research)
4. Follow sequential workflow
5. Update issues as progress is made
6. Conduct code review at each phase