randomayzer/docs/VK_CLIENT.md

VK Client Architecture & Integration Guide

The VK Integration layer is structured into modular, decoupled components located under src/integrations/vk/.

---

Architecture Overview

[SocialMediaProvider Interface]
               │
               ▼
        [VkProvider]
               │
               ▼
          [VkClient]
      ┌────────┼────────┐
      │        │        │
      ▼        ▼        ▼
 [VkAuth] [VkRateLimit] [VkRetry]
      │        │        │
      └────────┼────────┘
               │ (POST https://api.vk.com/method/*)
               ▼
           [VK API]

Core Components

1. VkClient (src/integrations/vk/vk-client.ts):

   • Centralizes low-level HTTP communication with VK API.
   • Enforces default API version 5.199.
   • Manages timeouts with AbortController (default 15s).
   • Coordinates outbound rate limiting and retry backoff.
   • Provides universal pagination helper fetchPaginatedVk.

2. VkAuthContext (src/integrations/vk/vk-auth.ts):

   • Represents typed access tokens (SERVICE, USER, COMMUNITY).
   • Ensures tokens are never leaked into logs, error messages, or persistent audit records.

3. VkRateLimiter (src/integrations/vk/vk-rate-limit.ts):

   • Throttles outbound requests according to VK API thresholds (default: 10 req/sec configurable).

4. executeWithRetry (src/integrations/vk/vk-retry.ts):

   • Handles exponential backoff with full jitter for retryable transient errors (5xx server errors, rate limits, network timeouts).
   • Fast-fails non-retryable errors (auth errors, permissions, private resources, validation).

---

Pagination & Scalability

• No Artificial Caps: Previous limits (e.g. 5,000 likes or 1,000 comments) have been completely removed.
• Likes: Uses likes.getList with filter=likes&extended=1 in batches of 100 up to the total post likes count.
• Comments: Uses wall.getComments with extended=1 and profile enrichment.
• Subscription Checks: Batches up to 500 user IDs per groups.isMember call.