FastComments Java SDK

Дайте вашему код‑агенту контекст FastComments, который ему нужен — виджеты, конфигурацию, Secure SSO, REST API и SDK:

npx skills add fastcomments/skills

Работает с Claude Code, Codex, Cursor, Copilot, Gemini и любым другим агентом, поддерживаемым skills CLI.

Maven

Добавьте репозиторий Repsy в POM вашего проекта:

<repositories>
    <repository>
        <id>repsy</id>
        <name>FastComments Maven Repository on Repsy</name>
        <url>https://repo.repsy.io/mvn/winrid/fastcomments</url>
    </repository>
</repositories>

Затем добавьте необходимые зависимости:

<dependencies>
    <!-- Клиент API -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- Основная библиотека (включает SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- Библиотека PubSub (для живых событий) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>3.1.1</version>
    </dependency>
</dependencies>

Gradle

Добавьте репозиторий Repsy в файл build.gradle:

repositories {
    mavenCentral()
    maven {
        url "https://repo.repsy.io/mvn/winrid/fastcomments"
    }
}

dependencies {
    // Клиент API
    implementation "com.fastcomments:client:3.1.1"
    
    // Основная библиотека (включает SSO)
    implementation "com.fastcomments:core:3.1.1"
    
    // Библиотека PubSub (для живых событий)
    implementation "com.fastcomments:pubsub:3.1.1"
}

Содержимое библиотеки

Эта библиотека содержит три модуля: сгенерированный клиент API, основную Java‑библиотеку, которая содержит написанные вручную утилиты для упрощения работы с API, и модуль pubsub, который представляет собой библиотеку для подписки на потоки изменений.

• Документация библиотеки клиента API
• Документация основной библиотеки, включая примеры SSO
• Документация библиотеки PubSub

Публичные и защищённые API

Для клиента API существует три класса, DefaultApi, PublicApi и ModerationApi. DefaultApi содержит методы, требующие вашего API‑ключа, а PublicApi содержит методы, которые можно вызывать напрямую из браузера/мобильного устройства и т.д. без аутентификации.

ModerationApi предоставляет обширный набор живых и быстрых API модерации. Каждый метод ModerationApi принимает параметр sso и может аутентифицироваться через SSO или сессионный cookie FastComments.com.

Использование аутентифицированных API (DefaultApi)

Важно: Перед выполнением аутентифицированных запросов необходимо установить ваш API-ключ в ApiClient. Если этого не сделать, запросы завершатся ошибкой 401.

import com.fastcomments.invoker.ApiClient;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.api.DefaultApi;
import com.fastcomments.model.*;

public class Example {
    public static void main(String[] args) {
        // Создание и настройка API-клиента
        ApiClient apiClient = new ApiClient();

        // ОБЯЗАТЕЛЬНО: Установите ваш API-ключ (получите его в панели управления FastComments)
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // Создание экземпляра API с настроенным клиентом
        DefaultApi api = new DefaultApi(apiClient);

        // Теперь можно выполнять аутентифицированные вызовы API
        try {
            // Пример: Добавление SSO-пользователя
            CreateAPISSOUserData userData = new CreateAPISSOUserData();
            userData.setId("user-123");
            userData.setEmail("user@example.com");
            userData.setDisplayName("John Doe");

            AddSSOUserAPIResponse response = api.addSSOUser("YOUR_TENANT_ID", userData)
                .execute();
            System.out.println("User created: " + response);

        } catch (ApiException e) {
            System.err.println("Error: " + e.getResponseBody());
            // Частые ошибки:
            // - 401: API-ключ отсутствует или недействителен
            // - 400: Не прошла валидация запроса
        }
    }
}

Использование публичных API (PublicApi)

Публичные эндпоинты не требуют аутентификации:

import com.fastcomments.api.PublicApi;
import com.fastcomments.invoker.ApiException;

PublicApi publicApi = new PublicApi();

try {
    var response = publicApi.getCommentsPublic("YOUR_TENANT_ID", "page-url-id")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

Использование API модерации (ModerationApi)

ModerationApi управляет панелью модератора. Каждый метод принимает параметр sso, идентифицирующий SSO-аутентифицированного модератора, от имени которого выполняется запрос:

import com.fastcomments.api.ModerationApi;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.model.*;

ModerationApi moderationApi = new ModerationApi();

try {
    // Список комментариев, ожидающих модерации
    ModerationAPIGetCommentsResponse response = moderationApi.getApiComments()
        .sso("YOUR_SSO_TOKEN")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

Частые проблемы

1. Ошибка 401 "missing-api-key": Убедитесь, что вы вызываете apiClient.setApiKey("YOUR_KEY") перед созданием экземпляра DefaultApi.
2. Неправильный класс API: Используйте DefaultApi для серверных аутентифицированных запросов, PublicApi — для клиентских/публичных запросов.
3. Null API-ключ: SDK молча пропустит аутентификацию, если API-ключ равен null, что приведёт к ошибкам 401.

Идентификаторы Broadcast

Вы увидите, что в некоторых вызовах API нужно передавать broadcastId. Когда вы получаете события, вам вернётся этот ID, чтобы вы могли игнорировать событие, если планируете оптимистично применять изменения на клиенте (что, вероятно, вы захотите сделать, поскольку это обеспечивает лучший пользовательский опыт). Передавайте здесь UUID. ID должен быть достаточно уникальным, чтобы не повторяться в рамках одной сессии браузера.